# CSV / Excel to JSON Converter (`flyerlin/csv-json-converter`) Actor

Convert CSV, TSV, and Excel files to JSON or JSONL, or flatten JSON into CSV-ready rows. Includes type inference, nested header handling, delimiter sniffing, and duplicate removal.

- **URL**: https://apify.com/flyerlin/csv-json-converter.md
- **Developed by:** [林 吴](https://apify.com/flyerlin) (community)
- **Categories:** Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.05 / 1,000 csv/json rows

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CSV / Excel to JSON Converter

Convert tabular files to clean JSON, or turn JSON into CSV-ready flat rows. Built for ETL jobs, spreadsheet imports, and automation workflows.

### What it does

- Reads CSV, TSV, JSON, JSONL, and Excel (`.xlsx`) files
- Auto-detects the format: XLSX by file signature, JSON/JSONL by content, otherwise CSV
- Sniffs CSV delimiters (`;`, `|`, tabs) and handles UTF-8 BOM, GB18030, and CP1252 encodings
- Converts CSV/Excel to JSON with type inference (numbers, booleans, nulls)
- Splits dot-notation headers such as `user.email` into nested objects
- Flattens nested JSON into dot-notation columns when the target is CSV
- Optional duplicate-row removal
- Handles multi-sheet Excel workbooks and adds a `_sheet` field per row

### Input

| Field | Type | Description |
| --- | --- | --- |
| `raw_text` | string | Raw CSV, TSV, JSON, or JSONL content |
| `source_url` | string | Optional public URL to a file (max 30 MB); ignored when `raw_text` is set |
| `source_format` | enum | `auto`, `csv`, `tsv`, `json`, `jsonl`, `xlsx` |
| `target_format` | enum | `json` pushes nested objects; `csv` pushes flat rows |
| `delimiter` | string | Optional delimiter override; empty = auto |
| `sheet_name` | string | Optional Excel sheet; empty = all sheets |
| `flatten` | boolean | Flatten nested JSON for CSV output |
| `nest_headers` | boolean | Split dot-notation headers into nested objects |
| `infer_types` | boolean | Convert CSV strings to numbers/booleans/nulls |
| `dedupe` | boolean | Remove identical rows after conversion |
| `max_rows` | integer | Input cap, default 20,000 (0 = unlimited) |

Example: CSV to JSON

```json
{
  "raw_text": "name,email,age,active\nLin,lin@example.com,42,true",
  "target_format": "json",
  "infer_types": true
}
```

Example: JSON to CSV-ready rows

```json
{
  "raw_text": "[{\"user\": {\"name\": \"Lin\", \"email\": \"lin@example.com\"}, \"score\": 42}]",
  "target_format": "csv"
}
```

Output for the JSON-to-CSV example:

```json
{
  "user.name": "Lin",
  "user.email": "lin@example.com",
  "score": 42
}
```

### Output

Each converted row is pushed as one item to the default dataset. For `target_format: csv`, rows are flat and can be exported as CSV directly from the Apify dataset UI or API. The run summary is stored in the key-value store under `SUMMARY`.

### Pricing

Pay per event. You pay **$0.00001 per output row**, which is **$0.01 per 1,000 rows**. Failed runs are not charged the per-row fee.

### Notes

- Dates are kept as strings to avoid silent format changes; convert them downstream if needed.
- For Excel files, only the first row of each sheet is treated as the header.
- No external AI model is called; conversions are deterministic and fast.

# Actor input Schema

## `raw_text` (type: `string`):

Raw CSV, TSV, JSON, or JSONL content. Ignored when source_url is used.

## `source_url` (type: `string`):

Optional public URL to a CSV, TSV, JSON, JSONL, or XLSX file (max 30 MB). Ignored when raw_text is provided.

## `source_format` (type: `string`):

Input format. 'auto' detects XLSX by file signature, JSON/JSONL by content, otherwise CSV.

## `target_format` (type: `string`):

'json' pushes one nested object per row. 'csv' pushes flat rows that can be exported as CSV from the dataset.

## `delimiter` (type: `string`):

Optional delimiter override, for example ';' or '|'. Leave empty for automatic detection.

## `sheet_name` (type: `string`):

Optional sheet to read. Leave empty to read all sheets; the sheet name is then added as a \_sheet field.

## `flatten` (type: `boolean`):

When the target is CSV, flatten nested JSON keys with dot notation and serialize arrays as JSON strings.

## `nest_headers` (type: `boolean`):

When converting CSV or Excel to JSON, split headers such as 'user.email' into nested objects.

## `infer_types` (type: `boolean`):

Convert CSV strings to numbers, booleans, and nulls. Dates stay as strings.

## `dedupe` (type: `boolean`):

Drop rows that are identical after conversion.

## `max_rows` (type: `integer`):

Maximum number of input rows to process (default 20,000, set 0 for unlimited).

## Actor input object example

```json
{
  "raw_text": "name,email,age,active\nLin,lin@example.com,42,true\nWu,wu@example.com,35,false",
  "source_format": "auto",
  "target_format": "json",
  "flatten": true,
  "nest_headers": true,
  "infer_types": true,
  "dedupe": false,
  "max_rows": 20000
}
```

# Actor output Schema

## `results` (type: `string`):

One dataset item per converted row.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "raw_text": `name,email,age,active
Lin,lin@example.com,42,true
Wu,wu@example.com,35,false`
};

// Run the Actor and wait for it to finish
const run = await client.actor("flyerlin/csv-json-converter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "raw_text": """name,email,age,active
Lin,lin@example.com,42,true
Wu,wu@example.com,35,false""" }

# Run the Actor and wait for it to finish
run = client.actor("flyerlin/csv-json-converter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "raw_text": "name,email,age,active\\nLin,lin@example.com,42,true\\nWu,wu@example.com,35,false"
}' |
apify call flyerlin/csv-json-converter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,flyerlin/csv-json-converter"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/yIYdAUsGPgZMc1cfg/builds/CboBzdnGftZU2Hy4H/openapi.json