# Japan e-Stat Official Statistics (Official API) (`jpopendata/japan-estat-statistics`) Actor

Search and download Japan's official government statistics via the official e-Stat API v3.0: find statistical tables, then pull their values with every dimension resolved to English names. You supply your own e-Stat application ID. Unofficial; not affiliated with the Statistics Bureau of Japan.

- **URL**: https://apify.com/jpopendata/japan-estat-statistics.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Categories:**
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 record scrapeds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Japan e-Stat Official Statistics (Official API v3.0)

**Search and download Japan's official government statistics through the official e-Stat API v3.0 (JSON) — find any statistical table, then pull its values with every dimension (area, sex, age, time…) resolved to readable English names.**

This Actor is a thin, polite client for the **official** e-Stat API v3.0 (`api.e-stat.go.jp`) of Japan's Portal Site of Official Statistics (政府統計の総合窓口). It is **not a scraper** — it calls the documented JSON API the way the Statistics Bureau intends, using **your own e-Stat application ID**, and returns each result as a flat record with a legal envelope (`source` / `sourceUrl` / `license` / `retrievedAt`) on every item.

> **Unofficial tool.** Independently built and maintained. **Not affiliated with, endorsed by, or connected to the Statistics Bureau of Japan, the Ministry of Internal Affairs and Communications, or the National Statistics Center.** e-Stat data is provided under the **政府標準利用規約（第2.0版）** (Government Standard Terms of Use v2.0), which permits commercial reuse with attribution; the required 出典 statement **「出典：政府統計の総合窓口(e-Stat)」** is embedded in the `license` of every record.

***

### Quick start — verified input

Copy, paste, replace the key, run (verified against mock API fixtures in `npm test`; a live run needs your own application ID — see the next section for how to get one in two minutes):

```json
{
  "appId": "<your key>",
  "mode": "search_tables",
  "searchWord": "人口",
  "maxItems": 100
}
```

Get the key at https://www.e-stat.go.jp/mypage/user/preregister (free) → マイページ → **API機能（アプリケーションID発行）** → copy the appId. Then download a table's values with `{"mode": "get_data", "statsDataId": "<id from the search output>"}`.

### ⚠️ You need your own e-Stat application ID

This Actor **does not bundle an API key.** You must supply your **own** free e-Stat application ID in the `appId` input.

1. Register a free e-Stat account: **https://www.e-stat.go.jp/mypage/user/preregister**
2. Issue an application ID (アプリケーションID) from your e-Stat My Page.
3. Paste it into this Actor's `appId` field (it is stored as a secret and redacted from all logs).

**Why this design?** The e-Stat API terms of use, **第3条第2項**, state: 「利用者は、発行を受けたアプリケーションIDを、第三者に譲渡・貸与してはならないものとします。」 — an application ID may **not** be transferred or lent to a third party. So this Actor never embeds a shared key: by running under **your** ID, every call stays inside **your** own e-Stat registration and any access limits apply to you. Compliance with the [e-Stat API terms of use](https://www.e-stat.go.jp/api/terms-of-use) is the responsibility of the application-ID holder — i.e. you.

### Source-display obligation (出典表示義務)

e-Stat data is released under the 政府標準利用規約（第2.0版）, which requires the source to be displayed. This Actor embeds the credit **「出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）」** verbatim in the `license` field of every record. If you display or republish the data, keep that credit visible.

### Two modes

#### 1. `search_tables` — find statistical tables (getStatsList)

Give a `searchWord` (free text, supports `AND` / `OR` / `NOT`) and/or a `statsCode`, and get back the matching statistical tables: their `statsDataId`, statistic name, table title, creating agency, survey/open dates, and a `tableUrl` deep link. At least one of `searchWord` / `statsCode` is required (this is a targeted search, not a full-catalogue dump).

#### 2. `get_data` — download a table's values (getStatsData)

Give a `statsDataId` (from a `search_tables` run) and get one record **per statistical value**, with each dimension code resolved to its name. Optionally narrow with `narrowingCond` (e-Stat classification codes: `cdArea`, `cdTime`, `cdTab`, `cdCat01`–`cdCat03`).

### Sample output

**search\_tables** (dataset item):

```json
{
  "statsDataId": "0003448233",
  "statsName": "Population Census",
  "title": "Population by Age (5-Year Groups) and Sex - Japan, Prefectures",
  "govOrg": "Ministry of Internal Affairs and Communications",
  "statField": "Population and Households",
  "surveyDate": "202010",
  "openDate": "2021-11-30",
  "smallArea": 0,
  "overallTotalNumber": 47088,
  "tableUrl": "https://www.e-stat.go.jp/dbview?sid=0003448233",
  "source": "政府統計の総合窓口(e-Stat) API / Portal Site of Official Statistics of Japan (e-Stat), Statistics Bureau of Japan",
  "sourceUrl": "https://www.e-stat.go.jp/api/",
  "license": "出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）。政府標準利用規約（第2.0版）… Unofficial …",
  "retrievedAt": "2026-08-26T09:12:44Z"
}
```

**get\_data** (dataset item):

```json
{
  "statsDataId": "0003448233",
  "value": 126146099,
  "valueRaw": "126146099",
  "unit": "person",
  "time": "2020",
  "timeCode": "2020000000",
  "area": "All Japan",
  "areaCode": "00000",
  "dimensions": [
    { "id": "tab", "name": "Tabulated items", "code": "020", "label": "Population", "unit": "person" },
    { "id": "cat01", "name": "Sex", "code": "000", "label": "Both sexes", "unit": null },
    { "id": "area", "name": "Area", "code": "00000", "label": "All Japan", "unit": null },
    { "id": "time", "name": "Time", "code": "2020000000", "label": "2020", "unit": null }
  ],
  "source": "政府統計の総合窓口(e-Stat) API …",
  "sourceUrl": "https://www.e-stat.go.jp/api/",
  "license": "出典：政府統計の総合窓口(e-Stat) …",
  "retrievedAt": "2026-08-26T09:12:44Z"
}
```

When the source publishes a non-number (e.g. `-` = not applicable, `***` = not available), `value` is `null` and the original marker is kept in `valueRaw` — passed through honestly rather than zero-filled.

### Input example

```json
{
  "appId": "<your key>",
  "mode": "get_data",
  "statsDataId": "0003448233",
  "narrowingCond": { "cdArea": "13000", "cdTime": "2020000000" },
  "lang": "E",
  "maxItems": 5000
}
```

#### Common input mistakes

| Mistake | Correct |
|---------|---------|
| `"appId": "<your key>"` left as is / empty | paste your real e-Stat appId (the run fails immediately with a link to get one) |
| `{"appId": "…", "mode": "search_tables"}` with no `searchWord`/`statsCode` | add `"searchWord": "人口"` |
| `{"mode": "search_tables", "statsDataId": "0003448233"}` | `"mode": "get_data"` — statsDataId is a get\_data field (the Actor switches for you when `mode` is omitted) |
| `"statsCode": "国勢調査"` | the 8-digit code: `"00200521"` |
| `"surveyYears": "2015-2020"` | `"2015"`, `"202010"` or `"201501-202012"` (yyyymm ranges) |
| `"lang": "jp"` / `"japanese"` | accepted — canonical values are `"E"` / `"J"` |
| `"narrowingCond": {"area": "13000"}` | key names are `cdArea`, `cdTime`, `cdTab`, `cdCat01`–`cdCat03` |

#### Empty results?

A run that finds nothing completes with 0 items and a warning in the log (not a failure). Typical causes: an English `searchWord` (most tables are indexed in Japanese — try `人口` instead of `population`), a `surveyYears` window in which the statistic was not surveyed, or a `narrowingCond` code that is not one of the table's own classification codes (get the codes from the table's metadata first). Broaden the search or drop the filter and retry. e-Stat returns a `RESULT.STATUS` error for a bad appId — that fails the run visibly.

### Pricing

Pay per result — see the pricing tab. A `search_tables` run is a handful of tables; a `get_data` run is one record per statistical value and can be large, so use `narrowingCond` and `maxItems` to scope it.

### FAQ

**Is this official?**
No. **Unofficial**, not affiliated with the Statistics Bureau of Japan. It is a client of e-Stat's official public API.

**Why is `appId` required and not provided?**
Because the e-Stat terms forbid transferring an application ID to a third party (第3条第2項). Your ID stays yours; it is entered as a secret and redacted from all logs.

**How fresh is the data?**
Live at request time — it is the same data e-Stat serves through its API.

**What languages are the names in?**
Set `lang` to `E` (English, default) or `J` (Japanese). e-Stat returns English names where the table provides them; otherwise names come through in Japanese.

**Any privacy concerns?**
None by construction: e-Stat publishes aggregate official statistics. Automated tests still assert no personal-data-shaped strings and full source attribution on every record.

**Rate limits / server load?**
One sequential connection, ≥ 1.5 s between requests, exponential backoff on 429/5xx, a hard per-run request budget, and no rate-limit evasion — the e-Stat terms (第8条) forbid 「短時間における大量のアクセス」, so a persistent block fails the run visibly.

### Search terms this Actor answers

japan government statistics api · e-stat data · japan census data · japan official statistics english · e-Stat API actor · japan population statistics · japan economic statistics api · Statistics Bureau of Japan data · japan prefecture statistics · 政府統計 e-Stat API

### Note for the Apify automated build test

This Actor **requires** a valid personal e-Stat `appId` (secret) to make any live call, so Apify's default automated run test cannot pass unattended (no key). **An automated-test exemption is requested for this Actor** (same handling as other key-required API Actors). Functionality is covered by the unit test suite (`npm test`, 27 tests) over mock API fixtures; a live run needs the buyer's own application ID.

***

*Official API: e-Stat API v3.0 — https://www.e-stat.go.jp/api/ . Terms: https://www.e-stat.go.jp/api/terms-of-use (政府標準利用規約 v2.0, commercial use permitted with attribution — embedded in every record). Credit 「出典：政府統計の総合窓口(e-Stat)」 is embedded in every record. Unofficial; not affiliated with the Statistics Bureau of Japan.*

# Actor input Schema

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

REQUIRED. YOUR OWN e-Stat application ID (アプリケーションID — a 40-character hex string). This Actor does NOT bundle a shared key — the e-Stat terms of use (第3条第2項) forbid transferring an application ID to a third party, so every request runs under your own registration and e-Stat's access limits apply to you. Register for free: https://www.e-stat.go.jp/mypage/user/preregister → マイページ → API機能(アプリケーションID発行) → copy the appId.

## `mode` (type: `string`):

`search_tables` (default) finds statistical tables (getStatsList) — set searchWord and/or statsCode. `get_data` downloads the values of one table (getStatsData) — set statsDataId. Aliases "search"/"data" are accepted; if you pass only a statsDataId the Actor switches to get\_data for you. Example: "search\_tables".

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

search\_tables mode: free-text search over statistical tables. Japanese matches best (e.g. "人口", "世帯", "賃金"); English works where e-Stat provides it. Supports AND / OR / NOT (e.g. "人口 AND 世帯"). At least one of searchWord or statsCode is required in search\_tables mode.

## `statsCode` (type: `string`):

search\_tables mode (optional): 5-digit agency code or 8-digit government statistics code to restrict the table search, e.g. "00200521" (国勢調査 / Population Census), "00200502" (労働力調査). Find codes in the e-Stat statistics list.

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

search\_tables mode (optional): filter tables by survey period — yyyy (e.g. "2020"), yyyymm (e.g. "202010"), or yyyymm-yyyymm (e.g. "201501-202012").

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

get\_data mode (REQUIRED there): the e-Stat statistical table ID (statsDataId, 10 digits, e.g. "0003448233") to download — take it from a search\_tables run (the `statsDataId` field).

## `narrowingCond` (type: `object`):

get\_data mode (optional): filters as e-Stat classification codes. Allowed keys: cdArea, cdTime, cdTab, cdCat01, cdCat02, cdCat03 — each a comma-separated code list, e.g. {"cdArea":"13000","cdTime":"2020000000"} (13000 = 東京都). Discover codes from the table's metadata.

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

Language for statistic / dimension / category names. "E" (default) returns English where e-Stat provides it; "J" returns Japanese. Aliases "en"/"ja"/"english"/"japanese" are accepted.

## `maxItems` (type: `integer`):

Maximum number of records (tables or values) to output, 1-100000 (default 1000). e-Stat paginates up to 100,000 rows per request; runs page under this automatically.

## `maxApiRequests` (type: `integer`):

Hard safety cap on API requests per run, 1-25 (default 10). Politeness (1 connection, >= 1.5 s spacing, exponential backoff on 429/5xx) is enforced in code; the e-Stat terms forbid short-burst bulk access.

## `proxyConfiguration` (type: `object`):

Apify proxy settings. Default is NO proxy (direct connection) — an official JSON API rarely needs one. The Actor backs off exponentially on 429/5xx and fails visibly on a persistent block; it never attempts rate-limit evasion.

## Actor input object example

```json
{
  "mode": "search_tables",
  "searchWord": "population census",
  "statsCode": "00200521",
  "surveyYears": "2020",
  "statsDataId": "0003448233",
  "lang": "E",
  "maxItems": 1000,
  "maxApiRequests": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Statistical table records (search\_tables) or statistical value records (get\_data), with source attribution (source, sourceUrl, license, retrievedAt) on every item.

# 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 = {
    "mode": "search_tables",
    "searchWord": "人口",
    "lang": "E",
    "maxItems": 1000,
    "maxApiRequests": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-estat-statistics").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 = {
    "mode": "search_tables",
    "searchWord": "人口",
    "lang": "E",
    "maxItems": 1000,
    "maxApiRequests": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-estat-statistics").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 '{
  "mode": "search_tables",
  "searchWord": "人口",
  "lang": "E",
  "maxItems": 1000,
  "maxApiRequests": 10
}' |
apify call jpopendata/japan-estat-statistics --silent --output-dataset

```

## MCP server setup

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

```

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/2Omx8KTsC5Ds6PEPD/builds/Ogo8wpWbsLp7NdhQG/openapi.json