Working with Japan’s corporate number (法人番号) API
What the NTA publishes, what its Web-API does and does not give you, and when hosting your own copy stops being worth it.
Japan's corporate number data is published free of charge. If there is a reason to use an API for it, that reason is not the data — it is the difficulty of ingesting it every day without ever missing one.
What the NTA publishes
Two downloads from the 法人番号公表サイト:
- 全件 (full) — a snapshot of every registered entity, refreshed monthly. The nationwide corporate-number file is a single archive of roughly 250 MB compressed and over 1 GB decompressed.
- 差分 (diff) — one file per business day, containing that day's changes.
There is also a Web-API, which requires an application to use.
The diff files expire
This is the part that matters most if you ingest it yourself.
Only the most recent 40 business days of diffs are published. There are always exactly 40 files, and the oldest drops off as each new one appears. Once a file leaves that window it is not available from the NTA or from anywhere else.
Newest
So if your ingestion has been broken for two months and you discover it afterwards, those diff files are gone. Re-downloading the full file restores current state, and the NTA will still return an individual entity's history on request — what cannot be rebuilt is the cross-section: what changed across every entity on the days you missed.
A nightly job failing quietly with nobody noticing is not an unusual event. With this data it is an irreversible one.
What actually goes wrong
Things you find out by running it, not by reading the specification:
File IDs are regenerated on every publication. The identifier in the download link changes each time, so it cannot be hardcoded — it has to be discovered from the listing page on every run. The number of files changes too, as the register grows.
Undocumented processing codes appear in live data. There are values in the real files that are in none of the published documentation. Aborting on an unrecognised code means your pipeline stops dead one morning; dropping the row means losing data you cannot re-fetch.
One code means "deleted". It appears only in diffs, never in the full file. Treating it as an update leaves you serving registrations that have been withdrawn — and your incremental database will disagree with one rebuilt from the full file, which you will not notice unless you compare them.
It does not fit in memory. The full file exceeds 1 GB decompressed. The obvious implementation that reads it into memory falls over.
When to ingest it yourself
Ingesting it yourself makes sense when:
- a periodic full snapshot is enough and you do not need change history
- you can run and monitor a daily job reliably
- the data cannot leave your infrastructure
An API makes sense when:
- you need to know when something changed
- you want to be told about specific companies
- you would rather not own a daily pipeline at all
What we do
curl https://api.daichodo.com/v1/corporations/8000000000001 \
-H "Authorization: Bearer dc_We ingest the diffs every business day and keep everything that has been published. Register the numbers you care about and we send a webhook when one changes — change detection starts at Standard.
Common questions
Is Japanese corporate number data free?
Yes. The NTA publishes both full and differential datasets at no cost. The cost is not acquisition — it is ingesting, normalising and never missing a day.
How long are the diff files available?
Only for a rolling recent window. Once a file falls out of it, that day's diff cannot be downloaded again - the NTA will still return an individual entity's history on request, but what changed across the whole register that day is only where somebody kept it.