# Japan Corporate Numbers — NTA 法人番号 (Official API) (`jpopendata/japan-corporate-numbers`) Actor

Look up Japan's registered corporations via the official National Tax Agency 法人番号 Web-API: by corporate number, by name, or by change period. Returns number, name, address, postcode, type and registry dates (English-keyed). Bring your own free NTA application ID. No personal data. Unofficial.

- **URL**: https://apify.com/jpopendata/japan-corporate-numbers.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 Corporate Numbers — National Tax Agency 法人番号 Web-API (Ver.4)

**Look up any registered Japanese corporation through the official National Tax Agency 法人番号システム Web-API — by 13-digit corporate number, by name, or by change period — and get the basic 3 information (corporate number, name, address) plus registry metadata as flat, English-keyed records.**

This Actor is a thin, polite client for the **official** 法人番号システム Web-API (Ver.4, `api.houjin-bangou.nta.go.jp`) of Japan's National Tax Agency (国税庁 法人番号公表サイト). It is **not a scraper** — it calls the documented XML API the way the NTA intends, using **your own free NTA application ID**, and returns each corporation 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 National Tax Agency of Japan.** The corporate-number data is provided under the **公共データ利用規約（第1.0版）** (Public Data License v1.0, CC-BY 4.0 compatible), which permits commercial reuse and redistribution with attribution; the required 出典 statement **「出典：国税庁法人番号公表サイト（国税庁）」** is embedded in the `license` of every record. **The final responsibility for lawful use rests with you, the user.** No personal data is handled — the API publishes only corporate registry information.

***

### 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):

```json
{
  "appId": "<your key>",
  "mode": "by_number",
  "corporateNumber": ["5111101000006"]
}
```

Get the ID at https://www.houjin-bangou.nta.go.jp/webapi/ (free) → **Web-API機能の利用申請** → the 13-digit application ID is issued to you. To search by name use `{"mode": "by_name", "name": "トヨタ自動車"}`; `prefecture` is a dropdown of the 47 English prefecture names (Japanese names / JIS codes also work via the API).

### ⚠️ You need your own NTA application ID

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

1. Apply for a free application ID from the Web-API page: **https://www.houjin-bangou.nta.go.jp/webapi/**
2. The NTA e-mails you a **13-digit application ID**.
3. Paste it into this Actor's `appId` field (it is stored as a secret and **redacted from all logs** — because the ID rides in the request URL, the Actor scrubs it from every log line).

**Why this design?** The Web-API terms of use (**Web-API機能利用規約 第9条(1)⑤**) forbid transferring, lending or disclosing the application ID to a third party. So this Actor never embeds a shared key: by running under **your** ID, every call stays inside **your** own NTA registration and any access limits apply to you. Compliance with the Web-API terms of use is the responsibility of the application-ID holder — i.e. you.

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

The corporate-number data is released under the 公共データ利用規約（第1.0版）, which requires the source to be displayed. This Actor embeds the credit **「出典：国税庁法人番号公表サイト（国税庁）（https://www.houjin-bangou.nta.go.jp/）」** verbatim in the `license` field of every record, together with the notice required by 第6条 of the Web-API terms (that the content is derived from the NTA Web-API but not guaranteed by the NTA). If you display or republish the data, keep that credit visible.

### Three modes

#### 1. `by_number` — look up by corporate number (`/4/num`)

Give one or more **13-digit corporate numbers** (`corporateNumber`) and get each corporation back. Numbers are fetched in batches of up to 10 per request (the NTA limit). Set `includeHistory: true` to also return the corporation's change-history rows.

#### 2. `by_name` — search by name (`/4/name`)

Give a `name` (商号又は名称) and get matching corporations. `nameMatch` is `prefix` (前方一致, default) or `partial` (部分一致). Optionally narrow with `prefecture` and `corporateType`. Set `includeHistoryName: true` to include past/superseded records.

#### 3. `by_period` — changes within a window (`/4/diff`)

Give `dateFrom` and `dateTo` (yyyy-MM-dd, **≤ 50-day window** — the NTA hard limit) and get every corporation newly assigned, changed or closed in that period. Optionally narrow with `prefecture` and `corporateType`. Large result sets are division-paged automatically.

### Sample output (dataset item)

```json
{
  "corporateNumber": "5111101000006",
  "name": "株式会社検索対象除外",
  "nameKana": "ケンサクタイショウジョガイ",
  "nameEn": "Kensaku Taisho Jogai Co., Ltd.",
  "prefectureName": "東京都",
  "prefectureNameEn": "Tokyo",
  "cityName": "千代田区",
  "streetNumber": "神田小川町一丁目１０番地",
  "prefectureCode": "13",
  "cityCode": "101",
  "postCode": "1000000",
  "corporateType": "301",
  "corporateTypeLabel": "株式会社",
  "process": "01",
  "processLabel": "新規",
  "closeDate": null,
  "assignmentDate": "2015-10-05",
  "latest": "1",
  "profileUrl": "https://www.houjin-bangou.nta.go.jp/henkorireki-johoto.html?selHoujinNo=5111101000006",
  "source": "国税庁法人番号公表サイト 法人番号システム Web-API / Corporate Number Publication Site Web-API, National Tax Agency of Japan",
  "sourceUrl": "https://www.houjin-bangou.nta.go.jp/",
  "license": "出典：国税庁法人番号公表サイト（国税庁）… 公共データ利用規約（第1.0版）… Unofficial …",
  "retrievedAt": "2026-08-26T12:00:00Z"
}
```

### Input example

```json
{
  "appId": "<your key>",
  "mode": "by_name",
  "name": "トヨタ自動車",
  "nameMatch": "partial",
  "prefecture": "Aichi",
  "maxItems": 500
}
```

#### Common input mistakes

| Mistake | Correct |
|---------|---------|
| `"appId": "<your key>"` left as is / empty | paste your real 13-digit NTA application ID (the run fails immediately with a link to get one) |
| `"corporateNumber": "T5111101000006"` (invoice-registration number) | drop the `T`: `"5111101000006"` — 13 digits |
| `{"mode": "by_number", "name": "トヨタ"}` | `"mode": "by_name"` (the Actor switches for you when `mode` is omitted) |
| `"name": "Toyota"` | Japanese trade name: `"トヨタ自動車"` (the register is Japanese) |
| `"dateFrom": "2026-01-01", "dateTo": "2026-06-30"` | at most 50 days per run — split into windows |
| `"prefecture": "Nagoya"` (a city) | `"prefecture": "Aichi"` — prefectures only |
| `"nameMatch": "exact"` | `"prefix"` (前方一致) or `"partial"` (部分一致) |

#### Empty results?

A run that finds nothing completes with 0 items and a warning in the log (not a failure). Typical causes: a `name` spelled differently from the register (try `"nameMatch": "partial"` and a shorter string, e.g. `トヨタ` instead of `トヨタ自動車株式会社`), a `prefecture`/`corporateType` filter that excludes the company, a corporate number that was never assigned, or a `by_period` window with no changes for the chosen filters. Loosen the filter and retry. The NTA API answers HTTP 400 with error code 011 for a bad application ID — that fails the run visibly.

### Pricing

Pay per result — see the pricing tab. A `by_number` run is one record per number (plus history rows if requested); a `by_name` / `by_period` run is one record per matching corporation and can be large, so use the filters and `maxItems` to scope it.

### FAQ

**Is this official?**
No. **Unofficial**, not affiliated with the National Tax Agency. It is a client of the NTA's official public Web-API.

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

**Any privacy concerns?**
None by construction: the 法人番号 Web-API publishes only a corporation's basic 3 information (商号・所在地・法人番号) and registry metadata — no representative name, no individual. Automated tests still assert no personal-data-shaped strings and full source attribution on every record.

**Can I use this commercially / redistribute the data?**
Yes — the data is under the 公共データ利用規約（第1.0版）(PDL v1.0, CC-BY compatible), which permits copying, adaptation, redistribution and commercial use provided you keep the 出典 credit visible. You are responsible for compliance with the terms.

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

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

### Search terms this Actor answers

japan corporate number api · houjin bangou api · 法人番号 API · japan company registry · japan business ID lookup · japan corporate number lookup · japan company address api · national tax agency corporate number · japan corporation search english · 国税庁 法人番号 Web-API

### Note for the Apify automated build test

This Actor **requires** a valid personal NTA `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, e.g. e-Stat / gBizINFO). Functionality is covered by the unit test suite (`npm test`, 29 tests) over mock XML fixtures; a live run needs the buyer's own application ID.

***

*Official API: 法人番号システム Web-API Ver.4 — https://www.houjin-bangou.nta.go.jp/webapi/ . Content under 公共データ利用規約（第1.0版）(commercial use & redistribution permitted with attribution — embedded in every record). Credit 「出典：国税庁法人番号公表サイト（国税庁）」 is embedded in every record. Unofficial; not affiliated with the National Tax Agency. Companion to the gBizINFO Actor (japan-gbizinfo-companies): 法人番号 = the basic 3 information for every corporation; gBizINFO = richer attributes (capital, employees, licenses) for the subset it covers.*

# Actor input Schema

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

REQUIRED. YOUR OWN National Tax Agency 法人番号 Web-API application ID (13-digit). This Actor does NOT bundle a shared key — every request runs under your own ID, sent in the `id` query parameter, and the Web-API terms forbid lending/disclosing it to a third party (第9条(1)⑤). The ID is stored as a secret and redacted from all logs. Register (free) and receive an application ID by e-mail/post: https://www.houjin-bangou.nta.go.jp/webapi/ → Web-API機能の利用申請.

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

`by_number` (default) looks up corporations by 13-digit corporate number (GET /4/num) — set corporateNumber. `by_name` searches by 商号/name (GET /4/name) — set name. `by_period` fetches corporations newly assigned/changed/closed within a date window (GET /4/diff) — set dateFrom and dateTo. Aliases "number"/"name"/"period" are accepted; if you pass only a name or only dates the Actor switches mode for you. Example: "by\_number".

## `corporateNumber` (type: `array`):

by\_number mode (REQUIRED there): one or more 13-digit Japanese corporate numbers (法人番号), e.g. \["5111101000006"]. A comma-separated string is also accepted; hyphens/full-width digits are tolerated. Fetched in batches of up to 10 per request.

## `name` (type: `string`):

by\_name mode (REQUIRED there): trade name / 商号又は名称 to search for, Japanese matches best, e.g. "トヨタ自動車".

## `nameMatch` (type: `string`):

by\_name mode: how the name matches — "prefix" (前方一致, default) or "partial" (部分一致). Japanese labels are accepted.

## `prefecture` (type: `string`):

by\_name / by\_period modes (optional): restrict by prefecture — pick one of the 47 prefectures by English name, e.g. "Tokyo", "Aichi" (via the API the Japanese name "東京都", the JIS code "13" or romanisations such as "osaka-fu" also work). Maps to the API `address` filter.

## `corporateType` (type: `string`):

by\_name / by\_period modes (optional): restrict by 法人種別 3-digit code (API `kind`), e.g. "301" (株式会社), "302" (有限会社), "305" (合同会社), "401" (外国会社等).

## `dateFrom` (type: `string`):

by\_period mode (REQUIRED there): start date of the change window, YYYY-MM-DD, e.g. "2026-08-01" (2026/08/01 and 20260801 are tolerated). API `from`.

## `dateTo` (type: `string`):

by\_period mode (REQUIRED there): end date of the change window, YYYY-MM-DD, e.g. "2026-08-31". At most 50 days after dateFrom (NTA hard limit). API `to`.

## `includeHistory` (type: `boolean`):

by\_number: also return the corporation's change-history rows (history=1). Default: latest only. "true"/"false" strings are tolerated.

## `includeHistoryName` (type: `boolean`):

by\_name: include past/superseded information in the search (change=1). Default: current only.

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

Maximum number of corporation records to output, 1-500000 (default 1000). Name/period results are division-paged automatically. PPE charges per record.

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

Hard safety cap on API requests per run, 1-100 (default 30). Politeness (1 connection, >= 1.2 s spacing, exponential backoff on 429/5xx) is enforced in code; the Web-API terms forbid 短時間における大量アクセス.

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

Apify proxy settings. Default is NO proxy (direct connection) — an official 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": "by_number",
  "corporateNumber": [
    "5111101000006"
  ],
  "name": "トヨタ自動車",
  "nameMatch": "prefix",
  "corporateType": "301",
  "dateFrom": "2026-08-01",
  "dateTo": "2026-08-31",
  "includeHistory": false,
  "includeHistoryName": false,
  "maxItems": 1000,
  "maxApiRequests": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Corporation records with source attribution (source, sourceUrl, license, retrievedAt) on every item. Corporate basic-3 public-registry data only; no personal data.

# 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": "by_number",
    "corporateNumber": [
        "5111101000006"
    ],
    "nameMatch": "prefix",
    "maxItems": 1000,
    "maxApiRequests": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-corporate-numbers").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": "by_number",
    "corporateNumber": ["5111101000006"],
    "nameMatch": "prefix",
    "maxItems": 1000,
    "maxApiRequests": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-corporate-numbers").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": "by_number",
  "corporateNumber": [
    "5111101000006"
  ],
  "nameMatch": "prefix",
  "maxItems": 1000,
  "maxApiRequests": 30
}' |
apify call jpopendata/japan-corporate-numbers --silent --output-dataset

```

## MCP server setup

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

```

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/ya0VD7dZwhEO9xsWh/builds/V2gwA9OgvnxQYLCNe/openapi.json