# Excel to JSON - Read XLSX, XLS & CSV Files to JSON (`gochujang/excel-extractor`) Actor

Read Excel file data from a public URL or base64 content and convert Excel to JSON. Convert CSV to JSON too; extract XLSX sheet names, column headers and rows for ETL.

- **URL**: https://apify.com/gochujang/excel-extractor.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** AI, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 27 total users, 10 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.10 / 1,000 row extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Excel to JSON — CSV to JSON, XLSX File Reader

Read Excel file data from a public URL or base64 input and convert XLSX, XLS, or CSV to JSON, including sheet names, headers, and rows.

### Quick start

Read one row from a small, public CSV file:

```json
{"fileUrl":"https://raw.githubusercontent.com/plotly/datasets/master/2014_usa_states.csv","maxRowsPerSheet":1}
```

One dataset item from this input:

```json
{"file_name":"2014_usa_states.csv","sheet":"Sheet1","row_count":1,"columns":["Rank","State","Postal","Population"],"rows":[{"Rank":"1","State":"Alabama","Postal":"AL","Population":"4849377.0"}],"status":"success","error_reason":null}
```

`file_name` names the downloaded file; `sheet` is the worksheet name or `Sheet1` for CSV. `columns` contains header names, `rows` contains the data, and `row_count` counts extracted data rows. `status` and `error_reason` report success or failure.

### Limits

The file URL must be publicly downloadable. Password-protected workbooks cannot be opened. Unknown or malformed formats return an error item; files with very many rows can take longer or use more memory. `maxRowsPerSheet` bounds extraction, and `sheetNames` selects Excel sheets only.

### Pricing

Pay-per-event:

| Event | Price |
|---|---|
| Actor start (charged by Apify, one per GB of run memory) | $0.001 |
| Data row extracted | $0.0001 |

There is no per-file fee. Example: a 5,000-row sales report = 5,000 × $0.0001 + start = **$0.501**.

### Use from AI agents (MCP)

Connect your agent to [Apify's official MCP server](https://mcp.apify.com) with an Apify token. Select the Actor tool `gochujang/excel-extractor`, pass the Quick start JSON as input, then retrieve its dataset items through the MCP server. No separate gateway is needed.

***

**Excel & CSV Extractor** converts `.xlsx`, `.xlsm`, `.xls`, and `.csv` files into structured JSON — one record per sheet or one record per row in flat mode. Pass a URL or base64-encoded file to get sheet names, headers, and row data.

Spreadsheet data is locked in binary formats that no API can read directly. This actor is the extraction layer that unlocks it — turning Excel reports, exported CSVs, and supplier data files into JSON that any system can consume.

***

### Why use Excel & CSV Extractor?

1. **AI data ingestion** — Feed spreadsheet data directly into Claude, GPT, or RAG pipelines. JSON output from this actor is ready for vector embedding, tabular Q\&A, or structured analysis without manual conversion.
2. **ETL pipeline automation** — Transform Excel reports and CSV exports into database-ready records. Trigger on new file uploads, extract the data, push to your API — fully automated with no manual steps.
3. **Financial report processing** — Extract P\&L, balance sheet, or budget rows from multi-sheet workbooks. The `sheetNames` filter lets you target specific tabs without processing the entire file.
4. **Supplier data import** — Parse product catalogs, inventory sheets, and price lists from supplier Excel files and sync them to your e-commerce or ERP system in real time.
5. **Multi-sheet workbook handling** — Extract all tabs from complex workbooks in one run. Each sheet becomes a separate output record with its own `sheet`, `row_count`, `columns`, and `rows` fields.

***

### How to use

1. Open the actor on Apify Store and click **Try for free**.
2. Paste a direct URL to your `.xlsx` or `.csv` file in `fileUrl` (or provide `fileBase64` for local files).
3. Set `sheetNames` to target specific tabs, or leave empty to extract all sheets.
4. Enable `flatMode: true` for one-record-per-row output (useful for large datasets feeding downstream systems).
5. Click **Start**. Returns one output record per sheet.

***

### Input options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `fileUrl` | string | — | Direct URL to `.xlsx`, `.xlsm`, or `.csv` file |
| `fileBase64` | string | — | Base64-encoded file content (alternative to URL) |
| `fileName` | string | auto | File name for format detection |
| `includeHeaders` | boolean | `true` | Treat first row as column headers |
| `sheetNames` | string\[] | `[]` (all) | Specific sheet names to extract |
| `maxRowsPerSheet` | integer | `10000` | Row cap per sheet (up to 500,000) |
| `flatMode` | boolean | `false` | One output record per row instead of per sheet |

***

### Output

**Per-sheet output (default):**

```json
{
  "file_name": "sales-report.xlsx",
  "sheet": "Q1 Sales",
  "row_count": 842,
  "columns": ["Date", "Product", "Region", "Revenue", "Units"],
  "rows": [
    {"Date": "2026-01-03", "Product": "Widget A", "Region": "US", "Revenue": "12400", "Units": "124"},
    {"Date": "2026-01-04", "Product": "Widget B", "Region": "EU", "Revenue": "8900", "Units": "89"}
  ]
}
```

**Flat mode (`flatMode: true`):**

```json
{
  "file_name": "sales-report.xlsx",
  "sheet": "Q1 Sales",
  "Date": "2026-01-03",
  "Product": "Widget A",
  "Region": "US",
  "Revenue": "12400",
  "Units": "124"
}
```

***

### Supported formats

| Format | Extension | Notes |
|--------|-----------|-------|
| Excel (modern) | `.xlsx`, `.xlsm` | Multi-sheet, formulas evaluated |
| CSV / TSV | `.csv`, `.tsv` | Auto-detects encoding (UTF-8, Latin-1) |

> **Legacy `.xls`**: Supported through the xlrd parser. Password-protected workbooks remain unsupported.

***

### FAQ

**Can it handle password-protected files?**
No — password-protected files cannot be opened without the password, and the actor has no mechanism for it. Remove password protection before uploading.

**What happens with formula cells?**
Formulas are evaluated to their current values. The raw formula string is not included in output — you get the calculated result.

**Is there a file size limit?**
No hard limit, but very large files (100MB+) will require longer run times. Use `maxRowsPerSheet` to cap output if you only need a sample.

**Can it process files from Google Drive or Dropbox?**
Yes — supported Google Drive, Google Sheets, and Dropbox sharing URLs are resolved to direct downloads. The file must be publicly accessible.

***

### Run it on a schedule / from your pipeline

**1. Apify Schedule.** Apify Console → **Schedules** → **+ New schedule**, pick Excel & CSV Extractor, set a cron such as `0 6 * * 1-5` (weekdays 06:00 UTC) and paste this input. The actor reads one file per run via `fileUrl`, so create one schedule (or one API call) per file:

```json
{
  "fileUrl": "https://example.com/exports/daily-sales.xlsx",
  "includeHeaders": true,
  "flatMode": true
}
```

**2. API call from your pipeline.** Run the actor and get the dataset items back in a single request:

```bash
curl -X POST "https://api.apify.com/v2/acts/gochujang~excel-extractor/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d @input.json
```

`input.json` holds the same JSON as above. Synchronous runs wait up to 300 seconds; for bigger batches call `POST /v2/acts/gochujang~excel-extractor/runs` and read the dataset when the run finishes.

**3. Webhooks.** For new-file triggers, have your storage or automation tool (S3 event, Zapier, Make, n8n) call the API above whenever a file arrives, and add an Apify webhook on `ACTOR.RUN.SUCCEEDED` (Actor → **Integrations**) to push the results to your system as soon as the run finishes.

***

### Related actors

- [PDF Text Extractor](https://apify.com/gochujang/pdf-text-extractor) — Extract text from PDF files (same document-to-JSON workflow)
- [Web to Markdown](https://apify.com/gochujang/web-to-markdown) — Convert web pages to clean text for AI pipelines
- [RSS Feed Parser](https://apify.com/gochujang/rss-feed-parser) — Parse RSS/Atom feeds into JSON

### Feedback

If this actor unlocks your spreadsheet data, a review helps others find it: [Leave a review on Apify Store](https://apify.com/gochujang/excel-extractor#reviews)

***

**Keywords:** Excel to JSON, XLSX parser, spreadsheet extractor, Excel scraper, XLSX to JSON, Excel data extraction, spreadsheet automation, ETL pipeline, Excel automation, XLS parser, Excel API, spreadsheet data, document parser

# Actor input Schema

## `fileUrl` (type: `string`):

Public direct URL to read Excel file data (XLSX/XLS) or convert CSV to JSON; for a small test use https://raw.githubusercontent.com/plotly/datasets/master/2014_usa_states.csv.

## `fileBase64` (type: `string`):

Base64-encoded Excel or CSV file content instead of fileUrl for Excel to JSON or CSV to JSON; for example, encode a local .csv file and set fileName to sample.csv.

## `fileName` (type: `string`):

Optional filename for format detection, such as report.xlsx or sample.csv. Derived from fileUrl when omitted.

## `includeHeaders` (type: `boolean`):

Treat the first row as column names and return object rows; for example, Rank,State,Postal,Population becomes four keys. Default: true.

## `sheetNames` (type: `array`):

Excel sheet names to extract, for example \["Sheet1"]. Leave empty to extract every sheet; CSV input uses one Sheet1 record.

## `maxRowsPerSheet` (type: `integer`):

Maximum data rows to extract from each sheet. Default: 10000.

## `flatMode` (type: `boolean`):

Output one dataset record per data row rather than per sheet; for example, two CSV data rows yield two records.

## Actor input object example

```json
{
  "fileUrl": "https://raw.githubusercontent.com/plotly/datasets/master/2014_usa_states.csv",
  "includeHeaders": true,
  "sheetNames": [],
  "maxRowsPerSheet": 10000,
  "flatMode": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 = {
    "fileUrl": "https://raw.githubusercontent.com/plotly/datasets/master/2014_usa_states.csv"
};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/excel-extractor").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 = { "fileUrl": "https://raw.githubusercontent.com/plotly/datasets/master/2014_usa_states.csv" }

# Run the Actor and wait for it to finish
run = client.actor("gochujang/excel-extractor").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 '{
  "fileUrl": "https://raw.githubusercontent.com/plotly/datasets/master/2014_usa_states.csv"
}' |
apify call gochujang/excel-extractor --silent --output-dataset

```

## MCP server setup

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

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/mLCxQsjuon0cW5sqC/builds/qm92ItHQWbfUCXpgU/openapi.json