CSV-to-JSON tool: The Ultimate Guide

The API samples the first 100 rows to identify consistent delimiters:

// The API automatically detects the delimiter
const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
  method: 'POST',
  headers: '{''
    'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
    'Content-Type': 'application/json',
  '}',
  body: JSON.stringify('{''
    file: csvContent, // CSV with any delimiter
    // No delimiter specified — auto-detection kicks in
  '}'),
'}');
const result = await response.json();
console.log(result.detected_delimiter); // e.g. "," or ";" or "\t"

Input: A CSV file with any supported delimiter (comma, semicolon, tab, pipe, or custom)

Output: JSON array of objects with the detected delimiter reported in response metadata

For files with ambiguous structure or custom delimiters, specify explicitly:

const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
  method: 'POST',
  headers: '{''
    'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
    'Content-Type': 'application/json',
  '}',
  body: JSON.stringify('{''
    file: csvFile,
    delimiter: '|' // Force pipe delimiter
  '}'),
'}');
const result = await response.json();

Real-world CSV files often contain tricky formatting that naive parsers fail on. Our tool handles these edge cases automatically:

name,description,price
"Smith, John","A product with, commas",29.99
"O''Brien","Another ""quoted"" value",15.50

// Input CSV:
// name,quote
// Alice,"She said ""Hello World"""
// Bob,"He replied ""Goodbye"""

// Output JSON:
// [
//   '{'' "name": "Alice", "quote": "She said \"Hello World\"" '}',
//   '{'' "name": "Bob", "quote": "He replied \"Goodbye\"" '}'
// ]

The parser uses a state machine to correctly track whether a delimiter is inside or outside of quoted fields, supporting both RFC 4180 standard quoting and common non-standard variations.

The API examines each column''s values to determine the best-fit type:

// Input CSV:
// name,age,price,active,created
// Alice,30,29.99,true,2024-01-15
// Bob,25,15.50,false,2024-02-20

// Output JSON with inferred types:
// [
//   '{''
//     "name": "Alice",    // string
//     "age": 30,           // integer
//     "price": 29.99,      // float
//     "active": true,      // boolean
//     "created": "2024-01-15"  // date
//   '}'
// ]

Automatically identifies header rows vs. data rows:

const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
  method: 'POST',
  headers: '{''
    'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
    'Content-Type': 'application/json',
  '}',
  body: JSON.stringify('{''
    file: csvFile,
    has_header: true, // Force header detection
    header_row: 0 // Specify header row (0-based)
  '}'),
'}');
const result = await response.json();

When auto-detection is enabled, the API analyzes the first row to determine if it contains column names by checking whether it differs in type distribution from subsequent rows.

CSV files from different systems use various character encodings. The API detects and converts automatically:

All output is normalized to UTF-8 JSON:

const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
  method: 'POST',
  headers: '{''
    'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
    'Content-Type': 'application/json',
  '}',
  body: JSON.stringify('{''
    file: csvFile,
    encoding: 'windows-1252' // Force specific encoding
  '}'),
'}');
const result = await response.json();

All output is guaranteed UTF-8 JSON, regardless of the input encoding. This ensures compatibility with all modern applications, databases, and APIs without any manual conversion steps.

Or go the opposite direction—flatten complex CSVs:

// Input: CSV with hierarchical headers
// Sales/2024/Q1, Sales/2024/Q2, Sales/2024/Q3
// 15000, 18000, 21000

// Output with flattening:
// [
//   '{''
//     "Sales_2024_Q1": 15000,
//     "Sales_2024_Q2": 18000,
//     "Sales_2024_Q3": 21000
//   '}'
// ]

Flattening simplifies nested CSV structures into flat key-value pairs, making it easy to import data into relational databases or flat file formats without losing information.

Simplest usage—just upload a file:

const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
  method: 'POST',
  headers: '{''
    'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
    'Content-Type': 'application/json',
  '}',
  body: JSON.stringify('{''
    file: csvFile, // File content as base64 or text
    infer_schema: true // Enable type inference
  '}'),
'}');
const result = await response.json();

console.log(result.json_data); // Array of objects
console.log(result.schema); // Inferred schema

Fine-tune behavior for complex files:

const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
  method: 'POST',
  headers: '{''
    'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
    'Content-Type': 'application/json',
  '}',
  body: JSON.stringify('{''
    file: csvFile,
    
    // Delimiter settings
    delimiter: ';', // Force semicolon delimiter
    quote_char: '"', // Quote character for escaping
    
    // Header settings
    has_header: true, // First row is header
    header_row: 0, // Header row index (0-based)
    
    // Encoding settings
    encoding: 'latin-1', // Force specific encoding
    
    // Type inference
    infer_schema: true,
    type_hints: '{''
      price: 'number',
      active: 'boolean',
      created_at: 'date'
    '}',
    
    // Nested structures
    array_columns: ['tags', 'categories'],
    array_delimiter: '|',
    nested_columns: ['address.*', 'contact.*'],
    
    // Performance
    chunk_size: 10 * 1024 * 1024, // 10MB chunks
    streaming: true, // Enable streaming mode
    
    // Validation
    validate_schema: true,
    required_columns: ['id', 'name'],
    
    // Output options
    compress: true, // Gzip compression
    pretty: false // Minified JSON
  '}'),
'}');
const result = await response.json();

Robust error handling for production systems:

async function convertCsvToJson(csvFile, options = '{''}') '{''
  const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
    method: 'POST',
    headers: '{''
      'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
      'Content-Type': 'application/json',
    '}',
    body: JSON.stringify('{'' file: csvFile, ...options '}'),
  '}');
  
  const result = await response.json();
  
  if (!response.ok) '{''
    throw '{'' code: result.error, message: result.message '}';
  '}'
  
  return result;
'}'

try '{''
  const result = await convertCsvToJson(csvFile);
  
  // Check for warnings
  if (result.warnings?.length > 0) '{''
    console.warn('Conversion warnings:', result.warnings);
  '}'
  
  return result.json_data;
  
'}' catch (error) '{''
  if (error.code === 'INVALID_DELIMITER') '{''
    // Try with manual delimiter
    return (await convertCsvToJson(csvFile, '{'' delimiter: ';' '}')).json_data;
    
  '}' else if (error.code === 'ENCODING_ERROR') '{''
    // Try with specific encoding
    return (await convertCsvToJson(csvFile, '{'' encoding: 'latin-1' '}')).json_data;
    
  '}' else if (error.code === 'SCHEMA_MISMATCH') '{''
    // Disable schema validation
    return (await convertCsvToJson(csvFile, '{'' validate_schema: false '}')).json_data;
    
  '}' else if (error.code === 'FILE_TOO_LARGE') '{''
    // Upgrade to enterprise tier or split file
    throw new Error('File exceeds size limit. Please upgrade or split the file.');
    
  '}' else '{''
    // Unknown error
    console.error('Conversion failed:', error);
    throw error;
  '}'
'}'

Process multiple files efficiently:

import pLimit from 'p-limit';

const limit = pLimit(5); // Max 5 concurrent requests

const files = [
  'products_2024_01.csv',
  'products_2024_02.csv',
  // ... 98 more files
];

async function convertCsvToJson(csvFile, options = '{''}') '{''
  const response = await fetch('https://apphighway.com/api/v1/csv-to-json', '{''
    method: 'POST',
    headers: '{''
      'Authorization': `Bearer $'{'process.env.APPHIGHWAY_API_KEY'}'`,
      'Content-Type': 'application/json',
    '}',
    body: JSON.stringify('{'' file: csvFile, ...options '}'),
  '}');
  return response.json();
'}'

const results = await Promise.all(
  files.map(file => 
    limit(async () => '{''
      try '{''
        const result = await convertCsvToJson(
          await readFile(file),
          '{'' infer_schema: true '}'
        );
        
        console.log(`Converted $'{'file'}': $'{'result.json_data.length'}' rows`);
        return '{'' file, success: true, data: result.json_data '}';
        
      '}' catch (error) '{''
        console.error(`Failed $'{'file'}':`, error.message);
        return '{'' file, success: false, error: error.message '}';
      '}'
    '}')
  )
);

const successful = results.filter(r => r.success).length;
const failed = results.filter(r => !r.success).length;

console.log(`Batch complete: $'{'successful'}' successful, $'{'failed'}' failed`);
console.log(`Total time: $'{'Math.round((Date.now() - startTime) / 1000)'}'s`);
console.log(`Points used: $'{'results.length * 2'}'`);

// Result: 100 files in ~3 minutes, 200 points total

Batch processing with concurrency limits allows you to convert hundreds of CSV files in minutes while staying within rate limits. 100 files take approximately 3 minutes and cost only 200 points.

Process 10 CSV files daily (5000-10000 products total)

Handle different delimiters (commas, semicolons) and encodings (UTF-8, Windows-1252)

Convert product categories from pipe-delimited strings to arrays

Parse nested address information into structured objects