DNK asset IDs

Every building JMAD knows about gets one identifier, minted once and never reassigned. This page covers the ID format, how allocation works, what happens when buildings merge or split apart, and why you should join your own data on the ID rather than on an address string.

Format

A DNK Asset ID looks like DNK-JP-13-01000000. The pattern is fixed: DNK-JP- followed by a 2-digit prefecture code, a hyphen, and an 8-digit sequence number. JMAD validates every ID against this pattern before it touches domain code, so a malformed ID never reaches the database as a lookup key.

13 is Tokyo's prefecture code. The eight digits are a per-prefecture counter — 100,000,000 of them, against roughly 3,000,000 buildings in Tokyo. The number carries no other meaning: it does not encode ward, building type, or the order buildings were surveyed in, and it is not dense. Counters are never rewound, so gaps in the run are normal and say nothing about a building.

One ID per building, keyed on source records

Consolidate groups a tile's observations into clusters by footprint overlap and normalized name matching, then allocates exactly one ID per cluster. What ties a cluster to an ID is its anchors: the set of (source, source record id) pairs behind its observations, for the sources that describe a building rather than an area.

Anchoring sources are OpenStreetMap, PLATEAU, Wikidata, EDINET, J-REIT disclosures, Green Archive, the green-building certifications, Mankan, and REINFOLIB. PLATEAU anchors on the official 建物ID (uro:buildingID), which is meant to persist across annual dataset releases, not on the per-file gml:id. The Address Base Registry, e-Stat, and Nominatim describe an area, not a building, and never anchor: anchoring on them would collapse every building in a 町丁目 into one ID.

Rerunning consolidate against the same building therefore reuses the existing ID, even when the footprint has moved, the name has been re-normalized, or the source that first described the building is gone — as long as one anchor survives. A cluster with no anchoring source at all is skipped and counted rather than given an ID, the same way a cluster JMAD cannot yet place in a prefecture is deferred to a later run.

📘

Note

The anchor set is the identity, not the allocation record. If every source drops a building's record, the anchors go with it and the next run mints a new ID for the same building. JMAD counts how often that happens; the count is what would justify adding a spatial fallback.

Invariants

Three properties hold for the life of an ID. Build against them.

• The prefecture prefix freezes at first allocation. If JMAD later resolves a building's location differently — a boundary case re-resolved, a better registry record — the building's page moves in the URL tree and the ID does not. The prefix records where the building was first placed; it is not a live claim about where it is.
• An ID is never reused. A retired ID is never handed to a different building, and the per-prefecture counter is never reset — not by a rebuild, not by a reset of the database. An ID you stored stays a statement about one building forever, even if that building later merges away.
• A merged ID redirects to its survivor. It does not go dead and it does not start pointing at something unrelated.

Merges and splits

When two previously separate clusters turn out to describe one building — they share an anchor — the older of the two IDs survives and the newer one gets a redirect row pointing at it. The loser's anchors are repointed at the survivor, its published page is withdrawn, and its building record is closed with a superseding record rather than deleted, so the history stays readable. Fetch a retired ID at its short link, /japan/id/<id>, and you get a single 301 straight to the survivor's permanent page. That redirect never chains: if the survivor itself is folded into a later merge, the existing redirect is rewritten to point at the new survivor directly, so a client following a link never has to hop twice.

curl -i https://dnk.co/japan/id/DNK-JP-13-01000000

The reverse happens too. Two clusters in one run can resolve to the same existing ID — because better geometry separated two buildings that used to overlap, or because an earlier merge was wrong. One of them keeps the ID and the other mints a fresh one and takes its own anchors with it. The cluster with more anchors keeps the ID; ties break on the highest-precedence anchoring source, then on the lowest source record id, so the outcome does not depend on the order the clusters happened to be processed in. No redirect is written for a split — nothing merged, so nothing should forward. A client holding the ID keeps pointing at whichever building kept it.

📘

Note

The change feed's changeKind is still only created or updated; there is no merged kind yet, so a merge shows up in the feed as an update to the survivor rather than as an event of its own. See data lifecycle.

A well-formed ID with no building behind it, or a malformed one, gets a different response. See rate limits and errors for the full set of shapes the short link and the API can return.

The permanent URL

Every building also has a human-readable path: /japan/<prefecture>/<ward>/<machi-aza>/<id>, where machi-aza (町字, roughly a town-block) is the smallest area segment. The segments are romaji slugs taken from the Address Base Registry, with the chōme kept as a suffix: 丸ビル (Marunouchi Building) sits at /japan/tokyo/chiyoda/marunouchi-2-chome/DNK-JP-13-01000000, because its address is 丸の内二丁目, not just 丸の内. See areas and coverage for how those segments are resolved.

Because the prefix freezes and the path does not, the prefecture in the ID and the prefecture in the path can in principle disagree. The path is the current answer; the ID is the original one. Resolve a building by ID and follow the path field rather than assembling a URL from the ID's digits.

Join on the ID, not the address

Addresses in Japan change block numbering, get re-romanized, and get typed inconsistently across sources: full-width and half-width characters, old and new ward boundaries, building names with or without a chōme (a numbered sub-block within an address). None of that touches the ID. If you're matching JMAD records against your own portfolio, store the DNK Asset ID against your own record once and refresh from it. An address match has to be redone every time either side's address string changes shape; an ID match doesn't.

The same argument applies across JMAD's own surfaces: the REST API, the Markdown twins, and the MCP server all key on the same ID, so a citation you pull from one is valid on the others.

See provenance and precedence for how the facts attached to an ID get chosen, and data lifecycle for what happens to a building's record over time.