# XLSX & CSV to JSON Converter (`ridgeline_apps/spreadsheet-converter`) Actor

Convert spreadsheet files (XLSX, XLSM, XLS, CSV, TSV) to clean JSON rows by URL or upload. All sheets or chosen ones, header detection, real dates and numbers, encoding and delimiter auto-detection.

- **URL**: https://apify.com/ridgeline_apps/spreadsheet-converter.md
- **Developed by:** [Promise Land Provision LLC](https://apify.com/ridgeline_apps) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 files

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

## XLSX & CSV to JSON Converter

Convert spreadsheet files to clean JSON: paste file links or upload files and get one JSON object per row, with column names from the header row. Export the result as JSON, CSV, XLSX or HTML, or read it through the API. Works with .xlsx, .xlsm, legacy .xls, .csv and .tsv files.

**Built for:** importing spreadsheets into apps and databases, feeding spreadsheet data to AI agents and automations (Make, Zapier, n8n), cleaning up CSV exports, and bulk-converting folders of workbooks.

### What you get

- **Every sheet, or just the ones you name.** Each row records which file, sheet and row number it came from.
- **Real types.** Numbers stay numbers, true/false stay booleans, and dates become ISO dates (`2026-03-05`, or `2026-03-04T09:30:00` when there is a time).
- **Clean column names.** It uses your header row (choose which row), fills blank headers as `column_3`, and makes duplicates unique (`Amount`, `Amount_2`).
- **CSV that just works.** Encoding (UTF-8, BOM, Latin-1 and more) and delimiter (comma, semicolon, tab, pipe) are detected automatically. Leading zeros such as ZIP codes and IDs are kept as text.
- **Tidy output.** Whitespace is trimmed and empty rows are skipped; both can be turned off.
- **Per-file summary** with sheet names and row counts, saved as `SUMMARY` in the run's key-value store.
- **Fair billing.** Files that fail, unsupported files and files with no data rows are never charged. The run stops cleanly at your maximum cost per run.

### How to use

1. Add file links (one per line) or upload files in **Spreadsheet files**.
2. Optional: list the **Sheets to convert** and set the **Header row**.
3. Click **Start**, then export the results in the format you need.

```bash
curl -X POST "https://api.apify.com/v2/acts/ridgeline_apps~spreadsheet-converter/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"files": ["https://example.com/orders.xlsx"], "sheets": ["Orders"]}'
```

### Input

| Field | Description | Default |
|---|---|---|
| `files` | Spreadsheet URLs or uploaded files | required |
| `sheets` | Sheet names to convert (empty = all) | all |
| `headerRow` | Row with column names; 0 = no header | 1 |
| `skipEmptyRows` | Leave out rows with no values | `true` |
| `trimWhitespace` | Trim text cells | `true` |
| `inferCsvTypes` | Turn CSV numbers and true/false into real types | `true` |
| `csvDelimiter` | `auto`, `comma`, `semicolon`, `tab` or `pipe` | `auto` |
| `maxRowsPerSheet` | Safety cap on rows per sheet | 100,000 |
| `maxFileSizeMb` | Larger files are skipped (free) | 50 |

### Output

One item per row:

```json
{ "_file": "orders.xlsx", "_sheet": "Orders", "_row": 2, "Order ID": 1001, "Customer": "Acme Co", "Amount": 1284.5, "Paid": true, "Date": "2026-03-04T09:30:00" }
```

Fields starting with `_` describe where the row came from. Files that fail come back as one item with an `_error` message, such as "This workbook is password-protected."

### Pricing

Pay per use, with no subscription:

- **Per file converted.**
- **Per row** output.

Files that fail or contain no data rows are free. The exact prices are on the Pricing tab, and you can set a maximum cost per run in the run options.

### FAQ

**Formulas?** You get the value the spreadsheet app last calculated and saved in the file. Formulas are not recalculated. Files generated by some tools never had values saved; their formula cells come back empty.

**OpenDocument (.ods), .xlsb or password-protected files?** These aren't supported. Save the file as .xlsx and try again. They're reported as errors and not charged.

**Merged cells?** The value appears in the top-left cell of the merged area; the other cells are empty.

**Where do my files go?** Files are downloaded into your own Apify run and processed there. Nothing is sent to any third-party service.

### Legal

Only process files you have the right to use. You're responsible for the files you submit and how you use the converted data.

Built on open-source software: openpyxl (MIT), xlrd (BSD), charset-normalizer (MIT) and httpx (BSD-3-Clause).

Questions or a feature request? Open an issue on the **Issues** tab.

# Actor input Schema

## `files` (type: `array`):

Paste file URLs (one per line) or upload files. Supports .xlsx, .xlsm, .xls, .csv and .tsv.

## `sheets` (type: `array`):

Sheet names to convert in XLSX and XLS files (not case-sensitive). Leave empty to convert every sheet.

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

Row number that holds the column names. Rows above it are skipped. Use 0 if there is no header row; columns are then named column_1, column_2 and so on.

## `skipEmptyRows` (type: `boolean`):

Leave out rows with no values.

## `trimWhitespace` (type: `boolean`):

Remove spaces at the start and end of text cells. Cells that become empty are set to null.

## `inferCsvTypes` (type: `boolean`):

Turn CSV text like 42, 3.5 and true into real numbers and booleans. Values with leading zeros, such as ZIP codes, stay as text. Cells in XLSX and XLS files always keep their own types.

## `csvDelimiter` (type: `string`):

Auto-detect works for most files.

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

Safety limit on rows converted from each sheet.

## `maxFileSizeMb` (type: `integer`):

Larger files are skipped and not charged.

## Actor input object example

```json
{
  "files": [
    "https://raw.githubusercontent.com/datasets/country-codes/main/data/country-codes.csv"
  ],
  "headerRow": 1,
  "skipEmptyRows": true,
  "trimWhitespace": true,
  "inferCsvTypes": true,
  "csvDelimiter": "auto",
  "maxRowsPerSheet": 100000,
  "maxFileSizeMb": 50
}
```

# Actor output Schema

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

No description

## `summary` (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 = {
    "files": [
        "https://raw.githubusercontent.com/datasets/country-codes/main/data/country-codes.csv"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ridgeline_apps/spreadsheet-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 = { "files": ["https://raw.githubusercontent.com/datasets/country-codes/main/data/country-codes.csv"] }

# Run the Actor and wait for it to finish
run = client.actor("ridgeline_apps/spreadsheet-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 '{
  "files": [
    "https://raw.githubusercontent.com/datasets/country-codes/main/data/country-codes.csv"
  ]
}' |
apify call ridgeline_apps/spreadsheet-converter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ridgeline_apps/spreadsheet-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/gFmV2n27JU4Fywglm/builds/5tjNVD6xDtQUkmIZR/openapi.json