Areas and coverage

JMAD organizes buildings into a three-level area hierarchy: prefecture, ward, and machi-aza (町字, roughly a town-block). Each level has its own hub page with aggregates, and each aggregate rolls up into the level above it.

Homepage loading

The /japan homepage streams its navigation, heading, search box, and loading placeholders while it reads building data. The location selectors, statistics, quick filters, the Explore the register map and list, and the Live areas cards replace those placeholders as the same HTML response completes. Placeholders do not represent zero counts or missing data.

Recognized crawler requests wait for the completed server render. If your integration reads homepage HTML, consume the complete response before extracting counts or coverage links. If a data load fails after streaming begins, the page shows an error with a reload link; the HTTP status may already be 200 because headers were sent with the loading shell.

The hierarchy

Hub URLs have no trailing slash; a request with one is redirected to the canonical form.

Slugs come from the Address Base Registry's own romaji columns (Tokyo, Chiyoda-ku, Marunouchi), lower-cased, with the -ku/-shi suffix dropped from wards and the chōme number kept as a -N-chome suffix on the machi-aza. Where the registry leaves the romaji blank, JMAD transliterates the registry's katakana reading instead. Every hub and building page also carries the Japanese name (location.names) and the official codes (location.codes: 2-digit prefecture, 6-digit local-government, 13-digit machi-aza) next to the slug, so you can join on whichever your own data uses.

Prefecture, ward, and machi-aza slugs are each their own branded type in the schema, so a segment that doesn't decode is a 400, not a lookup that quietly returns nothing. A slug that decodes but has no published buildings behind it is a 404, on the hub page and on GET /japan/api/v1/areas/... alike; an area that exists but matches none of the filters you applied is still a 200 with an empty list.

A machi-aza can straddle more than one ward, like 中之島・堂島 in central Osaka. When that happens, the area sits under its prefecture hub rather than being forced under one ward it only partly belongs to; the ward is still recorded on each building individually.

Choosing a location on the website

The home page and area-list filters include cascading Prefecture, Municipality or ward, and Machi-aza selectors under Browse by location. Each option is a link, so choosing one applies it immediately. Choose a prefecture to load its municipalities and wards, then choose one to load its machi-aza; a level stays disabled until its parent is chosen. Only areas with published records appear, each with its building count, and the selectors stay available when the active filters return no results.

You can stop at any level. Choosing a different prefecture or ward clears the selections below it, and All Japan clears the location.

On the home page, the location narrows Explore the register to that area, for example /japan?prefecture=tokyo&ward=chiyoda, and keeps the explore sort; All Japan returns to /japan. The home-page search box and quick filters always search all Japan. On an area list, the location keeps the other filters and sort order and restarts results at page 1; All Japan keeps the filters and shows all Japan at /japan/areas. See Search and pagination for the supported page filters.

Aggregates and per-field coverage

Every hub carries a building count and the timestamp of its most recently recorded building, so you can tell a stale area from an active one at a glance.

Coverage is measured per field: how many buildings in the area have a given field present against how many buildings exist there at all. A ward can show 100% coverage on addressJa and 20% on architect, because those fields come from different sources with different reach.

A field stored as null is missing and does not contribute to its coverage numerator. A non-null field contributes once, including a recorded zero or empty string; coverage measures presence, not whether a value is useful or independently verified. aliases and assetTypes each contribute once when their array has at least one entry. wikidataId appears in the coverage list but never counts as present. The denominator is every published building in the selected area, including buildings missing that field. PostgreSQL and the in-memory store apply the same rule.

curl https://dnk.co/japan/tokyo/chiyoda/marunouchi-2-chome

Address precision

A town match or representative town point does not establish a building address. JMAD's ABR loader currently supplies administrative location codes, not block or residence observations. Keep official IDs separate from display names and URL slugs.

The Digital Agency distinguishes formally maintained town text from trial map and finer address layers. See its ABR overview. Missing finer-layer records do not prove that an address or building is absent.

The JMA-31 implementation plan preserves original address text, official identifiers, source effective dates, and explicit town/block/residence precision. Block and residence ingestion is proposed work, not current coverage.

How tiles map to areas

Gather work is claimed one tile at a time, and a tile is normally one machi-aza polygon from the Address Base Registry. Where a machi-aza has no ABR polygon yet, the tile falls back to a JIS X 0410 3rd-level mesh cell covering the same ground, so gather always has something to claim even before the registry catches up.

⚠️

Caution

Today, only the mesh-fallback path is implemented. Machi-aza tiling itself needs an ABR footprint lookup that hasn't been built yet, so every tile gather claims right now is a mesh cell, not a real town-block polygon.

Municipality candidates come from the census polygons in each configured prefecture whose bounds intersect the mesh tile. A municipality's representative-point distance is not used to exclude it. The prefecture download is cached and reused across tiles; only intersecting features are passed to the address crosswalk.

Location resolution

A building's machi-aza is resolved first, from the e-Stat census boundary polygons and the Address Base Registry's representative points, in that precedence: a census polygon that contains the building's footprint centroid wins, falling back to the nearest ABR representative point within 300 m. The census polygon is linked to its registry row by name (chōme numerals folded so 八重洲一丁目 and 八重洲１丁目 match), and the linked observation carries the registry's official name, code, and slug with the census polygon as its geometry.

The ward and prefecture then follow from the machi-aza code itself: the first six digits name the ward, the first two the prefecture, so a building can never be filed under a ward that disagrees with the town-block it sits in. Only when no machi-aza resolved does JMAD look for a ward polygon or point containing the centroid, then a prefecture, then Nominatim's reverse-geocoded prefecture. How JMAD is built covers the pipeline stage that does this.

A building whose ward or machi-aza did not resolve falls back to the literal placeholder unresolved for that segment and, for the machi-aza, to a mesh-tile-derived slug — gather hasn't reached that tile yet, or a source returned nothing usable for it. Treat /japan/tokyo/unresolved/<mesh-tile-slug>/<id>-shaped paths as the exception, not the default.

A building whose prefecture does not resolve is not published at all. JMAD will not mint a permanent identifier it cannot place, so the cluster is deferred and counted, and picked up on a later run once e-Stat or the Address Base Registry covers its tile. There is no /japan/unresolved/… prefecture hub, and no ID begins DNK-JP-00-.

See DNK asset IDs for what the ID segments mean once resolved, and how JMAD is built for the rest of the pipeline these tiles feed into.

PLATEAU expansion prerequisites

The JMA-29 study archives catalog metadata and one selected building mesh each from Chiyoda 2025, Osaka 2025 and Fukuoka 2024. These small samples establish parser compatibility limits, not citywide completeness. Dataset fiscal edition, resource specification version and catalog modification time describe different things; none alone proves a building's effective date.

The Chiyoda sample has 477 buildings with roof-edge geometry. The Osaka and Fukuoka samples each have one building with ground-footprint geometry, which the current roof-edge-only adapter does not use. Some raw fields contain missing-value codes, including -9999 heights and 9999 storeys. Presence of an XML element therefore does not mean a usable fact is available.

JMA-56 will retain catalog and licence manifests. JMA-57 will add footprint and multipart support plus edition-specific missing-value interpretation after the shared geometry prerequisite. JMA-58 will then measure municipality pilots by field and rejection reason. These are proposed stages, not newly deployed coverage.

The catalogs link to the PLATEAU site policy. Preserve source attribution, processing notices and any resource-specific rights terms.

OSM coverage limits and proposed expansion

The current OSM loader requests building ways only. Buildings represented through relations can therefore be absent, and current coverage must not be read as a complete census.

JMA-30 proposes relation support followed by regional extracts and ordered updates. The archived Tokyo sample includes courtyard holes, outer rings assembled from several ways, disconnected components, and separate building outline/part relations. Its source database timestamp is May 6, 2026, although it was retrieved September 8. It demonstrates topology, not current coverage.

JMA-54 will implement relation parsing after multipart geometry and identity prerequisites. JMA-55 will then add extract and update processing with revision provenance and replay protection. A source deletion will withdraw OSM evidence without itself asserting demolition. These are proposed changes, not deployed capabilities.

OSM data remains subject to OpenStreetMap attribution and ODbL terms.

Names on the website

When a building name is missing, the website uses the other available language, then its recorded address, then postcode, then permanent DNK ID. Empty or duplicate secondary names are omitted. These display labels do not turn an address into a sourced name or fill missing facts in the API.

The area list's Build with this data panel provides API and MCP instructions. Its API example carries the area's slugs and search term. Table filters and sorting are separate from API search parameters.