# Excel to JSON (and JSON to Excel): XLSX Sheets to JSON Rows (`ucchiii/excel-to-json`) Actor

Excel to JSON: turn XLSX sheets into JSON rows with numbers and dates kept, plus a downloadable .json file. Give a JSON or NDJSON file instead and get an Excel sheet back. Empty input = free demo.

- **URL**: https://apify.com/ucchiii/excel-to-json.md
- **Developed by:** [Actor Factory](https://apify.com/ucchiii) (community)
- **Categories:** Developer tools, Automation, Integrations
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 converted rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

**Turn XLSX sheets into JSON rows (and JSON back into Excel)**

**Excel to JSON in one step: paste a link to an .xlsx file and get every row as a JSON object, with numbers kept as numbers and dates as ISO text, plus a downloadable .json file.** Give a JSON or NDJSON file instead and you get an Excel sheet back.

**Try it free:** leave the input empty and press **Start** — a built-in 2-sheet Excel sample is converted (not charged, rows carry `_demo: true`).

| Excel row | JSON row |
|---|---|
| `id` 1, `company` Blue Harbor Co, `monthly_usd` 49, `since` 10/01/2025 | `{"id": 1, "company": "Blue Harbor Co", "monthly_usd": 49, "since": "2025-01-10"}` |

- **Price:** $0.01 per 1,000 rows converted, charged per row ($0.00001 a row) — a 300-row sheet costs $0.003, 50,000 rows cost $0.50. Failed runs and the demo are free. Store discounts apply automatically: BRONZE −10%, SILVER −20%, GOLD −30%.
- **Big sheets are fine:** sheets are read row by row; a 1,000,000-row sheet converts within the default memory.

### How to use

1. **File URL**: a public link to an `.xlsx` file (Excel to JSON) or a `.json` / `.ndjson` file (JSON to Excel). The direction follows the file type.
2. Optional: **Sheet** (empty = first sheet, `*` = all sheets), **Header row** (default 1), **Output file name**.

```json
{ "fileUrl": "https://example.com/price-list.xlsx", "sheet": "*", "headerRow": 1 }
```

### Excel to JSON

- **One JSON object per row**, keys from the header row. Empty rows are skipped; empty header cells become `column_1`, `column_2`...; repeated names get `_2`, `_3`.
- **Values keep their type**: numbers stay numbers (`49`, `49.5`), `TRUE`/`FALSE` become `true`/`false`, dates become `2025-01-10` and date-times `2025-03-01T14:30:00`, empty cells `null`.
- **Formulas**: the result Excel saved with the file is used, the formula itself is never run (files written by some tools without Excel may have no saved result, which gives `null`).
- **Output**: the rows in the dataset (download as JSON, CSV or Excel from the run page) **and** one `.json` file with a download link — an array of rows, or for all sheets an object keyed by sheet name.

### JSON to Excel

- Accepts a JSON array of objects, an object holding one array (`{"items": [...]}`), or NDJSON (one object per line).
- **Nested objects become dot columns** (`address.city`); arrays are written as JSON text. Columns follow the order they first appear.
- **Safe for Excel**: text is always stored as text, so a value like `=HYPERLINK(...)` never runs as a formula; integers longer than 15 digits are kept as text so Excel does not round them.
- **Output**: one `.xlsx` file with a download link, and a summary item in the dataset.

### Limits (cannot be raised by input)

- Files up to 100 MB; 1,000,000 rows per run; Excel sheets hold at most 1,048,575 rows; cells longer than 32,767 characters are cut (the run tells you how many)
- Old `.xls` files (Excel 97-2003) are not supported — save them as `.xlsx` first. Password-protected files cannot be opened
- Set a maximum charge per run to cap spend; a file that needs more fails before anything is charged. Public files only (no login); links to internal network addresses are blocked

### Pricing

Pay per event: **$0.00001 per row converted** ($0.01 per 1,000 rows), charged per row. Failed runs and the demo are free.
On the Apify Free plan, the $5 of monthly platform credit covers about **500,000 rows** a month — enough to try it on real data.

### FAQ

**CSV files?** Use the CSV / XLSX Converter from the same developer — it handles CSV, TSV, Excel, JSON and NDJSON in any direction.
**Need only some rows?** Filter the JSON rows afterwards with the Filter Rows Actor from the same developer.

If this Actor saved you time, a rating on the Store helps others find it.

### More tools from the same developer

- [CSV / XLSX Converter](https://apify.com/ucchiii/csv-xlsx-converter) — convert CSV, TSV, Excel XLSX, JSON and NDJSON files or Apify datasets into each other
- [Dataset Splitter](https://apify.com/ucchiii/dataset-splitter) — split a dataset or CSV/JSON file into parts by rows, parts, column value or size, or take a random sample
- [Remove Duplicates](https://apify.com/ucchiii/dataset-dedup-merge) — merge Apify datasets and remove duplicates by the fields you choose
- [Google Sheets Export](https://apify.com/ucchiii/google-sheets-export) — export an Apify dataset to Google Sheets

# Actor input Schema

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

Public http(s) link to the file, up to 100 MB. An Excel file (.xlsx) becomes JSON; a JSON or NDJSON file becomes Excel. Leave empty for a free demo on a built-in Excel sample.

## `sheet` (type: `string`):

Excel to JSON: sheet name (case does not matter). Empty = the first sheet; \* = all sheets (each row gets a \_sheet field and the .json file is an object keyed by sheet name). JSON to Excel: name of the new sheet (default Data).

## `headerRow` (type: `integer`):

Excel to JSON: the row that holds the column names (default 1). Rows above it are skipped. 0 = no header row (columns are named column_1, column_2, ...).

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

Start of the output file name, for example 'prices' gives prices.json or prices.xlsx. Empty = taken from the source file name.

## Actor input object example

```json
{
  "headerRow": 1
}
```

# Actor output Schema

## `rows` (type: `string`):

Excel to JSON: one item per spreadsheet row. JSON to Excel: one item with the file name, rows, columns and the download link.

## `stats` (type: `string`):

Record STATS: direction, rows per sheet, output file, its size and download link, units charged.

## `files` (type: `string`):

The key-value store that holds the .json or .xlsx file.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ucchiii/excel-to-json").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("ucchiii/excel-to-json").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 '{}' |
apify call ucchiii/excel-to-json --silent --output-dataset

```

## MCP server setup

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

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/DirLv6qSMg41kgkmO/builds/n9QRMHSLTmbEbQFNR/openapi.json