# Japan Government Statistics API (e-Stat) (`panda_studio/estat-connector`) Actor

Search and download official Japanese government statistics from e-Stat (population, census, CPI, labour and more) as flat JSON/CSV rows with labels for every dimension. Published CSV mode works without an API key.

- **URL**: https://apify.com/panda\_studio/estat-connector.md
- **Developed by:** [panda studio](https://apify.com/panda_studio) (community)
- **Categories:** Business, Developer tools, News
- **Stats:** 2 total users, 1 monthly users, 66.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

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

## Japan Government Statistics API (e-Stat) — Search & Download as Clean JSON/CSV

Download **official Japanese government statistics from e-Stat (政府統計の総合窓口)** — population, census, consumer prices (CPI), labour, industry, household spending and thousands of other tables — as **flat, labelled JSON/CSV rows**. Search the table catalogue, fetch a table by ID, or download a published CSV with **no API key at all**.

### What does the e-Stat Connector do?

[e-Stat](https://www.e-stat.go.jp/) is Japan's official portal for government statistics. Its data is rich but awkward to use:

- the API's `getStatsData` puts numbers in `DATA_INF.VALUE` and the meaning of each number (area, period, category) in a separate `CLASS_INF`, joined only by bare codes such as `"@area": "13000"`
- published CSVs are served as Shift\_JIS/CP932 while the HTTP header says UTF-8, with notes and footnotes mixed into the rows

This Actor handles both and returns **one tidy row per value** (Table mode) or **one clean row per CSV line** (File mode), every row carrying the e-Stat attribution.

### Who is it for?

- **Analysts and data scientists** who need Japanese official statistics in pandas, BigQuery, Excel or a BI tool
- **Market researchers and consultants** sizing Japanese markets by prefecture or year
- **Journalists and academics** who need citable, sourced figures
- **Developers and AI agents** who want Japan statistics through a simple API or MCP tool instead of learning the e-Stat API

### Why use this Actor?

- **Works without registration** in File mode: paste a published file ID and get the data
- **Labels, not just codes** in Table mode: each dimension comes as `<dim>_code` + `<dim>_name`
- **Robust against real e-Stat quirks**: wrong charset headers, header-row detection, trailing footnotes (moved to `sourceNotes`), single-element objects that should be arrays
- **Official sources only**: e-Stat's REST API and its published file download; no scraping of HTML pages
- **Clear errors** for a missing or invalid `appId`, unknown IDs and documented e-Stat status codes
- **Small and fast**: Python standard library only; the 20-row demo runs in about 1.5 s

### Three modes (picked from your input)

| Mode | Input | API key (`appId`) | Output |
|---|---|---|---|
| **File** | `fileId` (statInfId) | **Not needed** | One row per CSV data row, with the file's own column names |
| **Table** | `statsDataId` | Needed (free) | One row per value, each dimension with code and label |
| **Search** | `searchWord` | Needed (free) | One row per matching table, including its `statsDataId` |

Priority if several are set: `fileId` > `statsDataId` > `searchWord`. With **no input at all**, the Actor runs a 20-row demo of file `000031524010` (population by prefecture) instead of failing.

### What data do you get?

| Field | Mode | Description |
|---|---|---|
| CSV columns (e.g. `都道府県名`, `西暦（年）`, `人口（総数）`) | File | The table's own headers and values as published |
| `_sourceFileId`, `_sourceUrl` | File | Which e-Stat file the row came from |
| `<dim>_code`, `<dim>_name`, `<dim>_label`, `<dim>_unit`, `time_year` | Table | Every dimension of the table (area, time, categories) as code + label, the dimension's name, its unit where given, and the year parsed from the time code |
| `value`, `valueRaw`, `unit`, `valueNote` | Table | Numeric value, original string, unit, and a note for placeholders such as `***` or `-` |
| `statsDataId`, `statName`, `tableTitle`, `cycle` | Table | Added when `includeTableMeta` is on |
| `attribution` | all | e-Stat credit line required by the terms of use |

A `RUN_SUMMARY` record in the key-value store holds the mode, row count, fetch time, source, request echo and any `sourceNotes` (footnotes).

### How much does it cost?

Pay per event: **$0.005 per row** plus **$0.00005 per run start**. Platform usage is included. `maxRows` (default 1,000) caps the rows, and therefore the cost, of each run.

| Scenario | Rows | Cost |
|---|---|---|
| Demo (no input) | 20 | about $0.10 |
| First 100 rows of a table (the prefilled `maxRows`) | 100 | about $0.50 |
| Population by prefecture, 1920–2015 (file `000031524010`, full) | 980 | about $4.90 |
| A filtered table (e.g. Tokyo only, 5 years) | tens of rows | well under $1 |

Use the `cdArea` / `cdTime` / `cdCat01` filters in Table mode to download only the slice you need. If you set a **maximum cost per run**, the Actor returns only as many rows as fit under it and marks `truncatedByMaxCharge` in `RUN_SUMMARY`.

### How to use it

**Without an API key (File mode)**

1. Open any table page on e-Stat and find its CSV download link, e.g. `.../file-download?statInfId=000031524010&fileKind=1`.
2. Put the `statInfId` value into **Published file ID**.
3. Click **Start** and download the dataset as JSON, CSV or Excel.

**With a free API key (Search and Table modes)**

1. Register at [e-stat.go.jp/api](https://www.e-stat.go.jp/api/) (ユーザ登録 → マイページ → API機能). The application ID is issued immediately and is free.
2. Enter it as **appId** (stored as a secret), or set the `ESTAT_APP_ID` environment variable.
3. Run **Search** with a keyword such as `消費者物価指数` or `人口推計` to find the `statsDataId`, then run **Table** with that ID and optional filters.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `appId` | string (secret) | — | e-Stat application ID (Table and Search modes) |
| `searchWord` | string | — | Keyword for the table catalogue |
| `statsDataId` | string | — | Table ID to fetch and flatten |
| `fileId` | string | — | Published file ID (statInfId); no key needed |
| `cdArea`, `cdTime`, `cdCat01` | array | — | Filters by area, time and first category codes (Table mode) |
| `surveyYears` | string | — | `2020`, `202001` or `202001-202012` (Search mode) |
| `maxRows` | integer | `1000` | Row cap per run (max 100,000); large tables are paginated |
| `includeTableMeta` | boolean | `true` | Add table ID, statistic name, title and cycle to each row |
| `lang` | string | `J` | Label language from the API: `J` or `E` |
| `requestIntervalSecs` | integer | `1` | Pause between paginated requests (minimum 0.5 s) |

```json
{
  "fileId": "000031524010",
  "maxRows": 100
}
```

### Output example

Real output (File mode, `fileId: 000031524010`, fetched 2026-09-24). The file has 980 data rows; this is the Tokyo row for 2015:

```json
{
  "都道府県コード": "13",
  "都道府県名": "東京都",
  "元号": "平成",
  "和暦（年）": "27",
  "西暦（年）": "2015",
  "注": "",
  "人口（総数）": "13515271",
  "人口（男）": "6666690",
  "人口（女）": "6848581",
  "_sourceFileId": "000031524010",
  "_sourceUrl": "https://www.e-stat.go.jp/stat-search/file-download?statInfId=000031524010&fileKind=1",
  "attribution": "出典：政府統計の総合窓口(e-Stat)(https://www.e-stat.go.jp/) / Source: Portal Site of Official Statistics of Japan (e-Stat)"
}
```

The file's footnotes are not mixed into the rows; they go to `RUN_SUMMARY.sourceNotes`, for example `"1)　沖縄県は調査されなかったため，含まれていない。"`.

File mode keeps values exactly as published (strings). Table mode adds a numeric `value` next to the original `valueRaw`.

### Tips

- Try File mode first: it needs no key and shows you the data before you register.
- In Table mode, start with a small `maxRows` and the `cdArea` / `cdTime` filters, then widen.
- `lang: "E"` returns English labels where e-Stat provides them (many tables are Japanese only).
- Keep the `attribution` column when you publish or share the data.

### Integrations and API

**Python**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("panda_studio/estat-connector").call(run_input={"fileId": "000031524010", "maxRows": 100})
rows = client.dataset(run["defaultDatasetId"]).list_items().items
```

**Node.js**

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });
const run = await client.actor('panda_studio/estat-connector').call({ fileId: '000031524010', maxRows: 100 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

**cURL** (CSV straight back)

```bash
curl -X POST "https://api.apify.com/v2/acts/panda_studio~estat-connector/run-sync-get-dataset-items?token=YOUR_API_TOKEN&format=csv" \
  -H "Content-Type: application/json" -d '{"fileId":"000031524010","maxRows":100}'
```

**MCP (Claude, Cursor, VS Code)**: `https://mcp.apify.com?tools=panda_studio/estat-connector`

### Data source, terms and attribution

- Source: Portal Site of Official Statistics of Japan (e-Stat), https://www.e-stat.go.jp/
- The [e-Stat terms of use](https://www.e-stat.go.jp/terms-of-use) allow commercial use, reproduction, translation and adaptation on condition that the source is credited and any processing is stated. Every row includes an `attribution` field.
- Not affiliated with or endorsed by the Statistics Bureau of Japan or e-Stat. No personal data is processed.

### FAQ

**Do I need an e-Stat API key?** Only for Search and Table modes. File mode works without one. The key is free and issued immediately.

**Where do I find a file ID?** In the CSV download link on an e-Stat table page: the value after `statInfId=`.

**Why is my value a string?** File mode keeps the published CSV as is. Table mode gives a numeric `value` plus the original `valueRaw`.

**What happens with `***` or `-` in the data?** In Table mode, `value` is `null` and the placeholder is explained in `valueNote`.

**Can I get English labels?** Set `lang` to `E`. e-Stat returns English labels only for tables that have them.

**How big can a download be?** Up to 100,000 rows per run (`maxRows`). The Actor paginates e-Stat automatically.

**What if I run it with an empty input?** It runs a 20-row demo (population by prefecture) instead of failing.

### Changelog

- **2026-09-24** — Empty input now runs a 20-row key-free demo instead of failing. Respects your maximum cost per run. Default memory lowered to 512 MB. README rewritten with real output and cost examples.
- **2026-09-23** — Output schema and README added; published on Apify Store.

# Actor input Schema

## `appId` (type: `string`):

Your free e-Stat API key. Register at <a href='https://www.e-stat.go.jp/api/' target='_blank'>e-stat.go.jp/api</a> (ユーザ登録 → マイページ → API機能), it is issued instantly and costs nothing. Required for <b>Search</b> and <b>Table ID</b> modes. <b>Not needed</b> if you only use 'Published file ID' below. Can also be supplied via the ESTAT\_APP\_ID environment variable.

## `searchWord` (type: `string`):

Keyword to search e-Stat's table catalogue, e.g. <code>消費者物価指数</code> (consumer price index), <code>人口推計</code> (population estimates). Returns one row per matching table including its <code>statsDataId</code>, which you then feed back in below. Requires appId.

## `statsDataId` (type: `string`):

Fetch and flatten one statistical table. Get the ID from a Search run, or from an e-Stat table URL. Requires appId. Takes priority over the search keyword.

## `fileId` (type: `string`):

Download a published e-Stat CSV directly. <b>This mode works without an appId.</b> Find the ID in the CSV download link on any e-Stat table page (<code>file-download?statInfId=<b>000031524010</b></code>). Verified example: <code>000031524010</code> = population by prefecture, 1920 onwards. Takes priority over the two options above.

## `cdArea` (type: `array`):

Restrict to specific area codes, e.g. <code>13000</code> (Tokyo). Leave empty for all areas. Applies to Table ID mode.

## `cdTime` (type: `array`):

Restrict to specific e-Stat time-axis codes, e.g. <code>2020000101</code>. Leave empty for all periods. Applies to Table ID mode.

## `cdCat01` (type: `array`):

Restrict to specific category codes of the table's first classification axis. Leave empty for all. Applies to Table ID mode.

## `surveyYears` (type: `string`):

Narrow a search by survey period: <code>2020</code> (year), <code>202001</code> (year+month), or <code>202001-202012</code> (range). Applies to Search mode.

## `maxRows` (type: `integer`):

Safety cap on rows returned in one run. Large tables are paginated automatically until this cap is reached.

## `includeTableMeta` (type: `boolean`):

Add the table ID, statistic name, table title and publication cycle to each output row. Handy for CSV exports; turn off for a leaner dataset.

## `lang` (type: `string`):

Language of labels returned by the e-Stat API.

## `requestIntervalSecs` (type: `integer`):

Pause between paginated requests to e-Stat. A minimum of 0.5 s is enforced internally to keep the load on the government server polite.

## Actor input object example

```json
{
  "searchWord": "消費者物価指数",
  "statsDataId": "0003448237",
  "fileId": "000031524010",
  "maxRows": 100,
  "includeTableMeta": true,
  "lang": "J",
  "requestIntervalSecs": 1
}
```

# Actor output Schema

## `statistics` (type: `string`):

All flattened e-Stat rows produced by this run (search results, statistical data, or downloaded file rows), stored in the default dataset.

# 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 = {
    "fileId": "000031524010",
    "maxRows": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("panda_studio/estat-connector").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 = {
    "fileId": "000031524010",
    "maxRows": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("panda_studio/estat-connector").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 '{
  "fileId": "000031524010",
  "maxRows": 100
}' |
apify call panda_studio/estat-connector --silent --output-dataset

```

## MCP server setup

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

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/viiwanaLA7h9RbFQ0/builds/v0SlVPnZodPegiwvb/openapi.json