Developer documentation
Resolve one Japanese postal code or address into a normalized response with explicit uncertainty, precision, and source provenance.
One request is enough. The only required input is query. Search outcomes return a normalized shape whether they are matched, partial, ambiguous, or not_found.
Authentication
Send your key with HTTP Bearer authentication. Never put a secret in a URL, browser bundle, or source repository.
Authorization: Bearer $JAPAN_API_KEYKeys are separated by test and live environments, shown in full only once when created, and can be revoked.
Make the first call
- Get a live key.Create one in Dashboard → API Keys.
- Set your secret.Store it as
JAPAN_API_KEY; never commit it. - Copy and run.The samples call
https://api.japanapistore.comand share the request object used by the contract tests.
curl -X POST "https://api.japanapistore.com/v1/address/resolve" \
-H "Authorization: Bearer ${JAPAN_API_KEY}" \
-H "Content-Type: application/json" \
--data '{"query":"〒100-0005 東京都千代田区丸の内1-1"}'POST /v1/address/resolve
Resolves one Japanese postal code or address. A completed search returns HTTP 200 for every normal search outcome.
Request
The request example and JSON Schema below come directly from @japan-api-store/contracts.
{
"query": "〒100-0005 東京都千代田区丸の内1-1"
}View contract schema
{
"$id": "ResolveRequest",
"additionalProperties": false,
"description": "A single Japanese postal code or address query.",
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"minLength": 1,
"maxLength": 512,
"type": "string"
}
}
}Response
All successful search responses include result, match, warnings, candidates, data_versions, and data_status. source_address preserves the submitted text; verified_address contains only officially matched components. verification.verified_level, addressing_system, public_data_status, and unresolved_components keep land-lot and residential-address evidence separate.
{
"request_id": "req_0123456789abcdef0123456789abcdef",
"success": true,
"input": {
"query": "〒100-0005 東京都千代田区丸の内1-1",
"detected_type": "address"
},
"result": {
"postal_code": "100-0005",
"source_address": "〒100-0005 東京都千代田区丸の内1-1",
"verified_address": {
"prefecture": "東京都",
"municipality": "千代田区",
"town_area": "丸の内",
"kyoto_street": null,
"chome": "1丁目",
"block": "1",
"lot": null,
"building_number": null,
"sub_number": null,
"building": null,
"building_name": null,
"room": null,
"full": "東京都千代田区丸の内1丁目1"
},
"verification": {
"verified_level": "machiaza",
"addressing_system": "unknown",
"unresolved_components": [],
"public_data_status": "available",
"conflict_detected": false,
"providers": [
{
"provider": "digital_agency_abr",
"source": "Digital Agency Address Base Registry",
"source_type": "government_open_data",
"verified_level": "machiaza",
"status": "stable"
}
]
},
"normalized_address": {
"prefecture": "東京都",
"municipality": "千代田区",
"town_area": "丸の内",
"kyoto_street": null,
"chome": "1丁目",
"block": "1",
"lot": null,
"building_number": null,
"sub_number": null,
"building": null,
"building_name": null,
"room": null,
"full": "東京都千代田区丸の内1丁目1"
},
"kana": {
"prefecture": "トウキョウト",
"municipality": "チヨダク",
"town_area": "マルノウチ"
},
"romaji": {
"prefecture": null,
"municipality": null,
"town_area": null
},
"codes": {
"jis_code": "13101",
"machiaza_id": "0001001",
"residential_block_id": null,
"residential_id": null,
"parcel_id": null
},
"location": {
"latitude": 35.6812,
"longitude": 139.7671,
"source": "digital_agency_abr"
}
},
"match": {
"status": "matched",
"score": 0.98,
"confidence": "high",
"match_level": "machiaza_detail",
"coordinate_level": "municipality",
"unmatched_text": null
},
"warnings": [],
"candidates": [],
"data_versions": {
"japan_post": "2026-07-31",
"abr": "3.0.51",
"abr_database": "3.0.51",
"normalizer": "1.0.0"
},
"data_status": {
"overall": "stable",
"japan_post": "stable",
"abr": "stable"
}
}View contract schema
{
"$id": "ResolveResponse",
"additionalProperties": false,
"description": "Normalized address result. score is an evidence score; confidence is not a probability.",
"type": "object",
"required": [
"request_id",
"success",
"input",
"result",
"match",
"warnings",
"candidates",
"data_versions",
"data_status"
],
"properties": {
"request_id": {
"pattern": "^req_[a-f0-9]{32}$",
"type": "string"
},
"success": {
"const": true,
"type": "boolean"
},
"input": {
"additionalProperties": false,
"type": "object",
"required": [
"query",
"detected_type"
],
"properties": {
"query": {
"type": "string"
},
"detected_type": {
"const": "address",
"type": "string"
}
}
},
"result": {
"additionalProperties": false,
"type": "object",
"required": [
"postal_code",
"source_address",
"verified_address",
"verification",
"normalized_address",
"kana",
"romaji",
"codes",
"location"
],
"properties": {
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_address": {
"type": "string"
},
"verified_address": {
"additionalProperties": false,
"type": "object",
"required": [
"prefecture",
"municipality",
"town_area",
"kyoto_street",
"chome",
"block",
"lot",
"building_number",
"sub_number",
"building",
"building_name",
"room",
"full"
],
"properties": {
"prefecture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"municipality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"town_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"kyoto_street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chome": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"block": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lot": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sub_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"room": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"full": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"verification": {
"additionalProperties": false,
"type": "object",
"required": [
"verified_level",
"addressing_system",
"unresolved_components",
"providers"
],
"properties": {
"verified_level": {
"anyOf": [
{
"const": "none",
"type": "string"
},
{
"const": "prefecture",
"type": "string"
},
{
"const": "municipality",
"type": "string"
},
{
"const": "machiaza",
"type": "string"
},
{
"const": "block",
"type": "string"
},
{
"const": "lot",
"type": "string"
},
{
"const": "building",
"type": "string"
},
{
"const": "residential_number",
"type": "string"
}
]
},
"addressing_system": {
"anyOf": [
{
"const": "residential_address",
"type": "string"
},
{
"const": "land_lot",
"type": "string"
},
{
"const": "unknown",
"type": "string"
}
]
},
"unresolved_components": {
"type": "array",
"items": {
"type": "string"
}
},
"public_data_status": {
"anyOf": [
{
"const": "available",
"type": "string"
},
{
"const": "public_data_not_available",
"type": "string"
},
{
"const": "unknown",
"type": "string"
}
]
},
"conflict_detected": {
"type": "boolean"
},
"providers": {
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"provider",
"source",
"source_type",
"verified_level",
"status"
],
"properties": {
"provider": {
"type": "string"
},
"source": {
"type": "string"
},
"source_type": {
"const": "government_open_data",
"type": "string"
},
"verified_level": {
"anyOf": [
{
"const": "none",
"type": "string"
},
{
"const": "prefecture",
"type": "string"
},
{
"const": "municipality",
"type": "string"
},
{
"const": "machiaza",
"type": "string"
},
{
"const": "block",
"type": "string"
},
{
"const": "lot",
"type": "string"
},
{
"const": "building",
"type": "string"
},
{
"const": "residential_number",
"type": "string"
}
]
},
"status": {
"anyOf": [
{
"const": "stable",
"type": "string"
},
{
"const": "preview",
"type": "string"
},
{
"const": "partial",
"type": "string"
},
{
"const": "unavailable",
"type": "string"
}
]
}
}
}
}
}
},
"normalized_address": {
"additionalProperties": false,
"type": "object",
"required": [
"prefecture",
"municipality",
"town_area",
"kyoto_street",
"chome",
"block",
"lot",
"building_number",
"sub_number",
"building",
"building_name",
"room",
"full"
],
"properties": {
"prefecture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"municipality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"town_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"kyoto_street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chome": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"block": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lot": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sub_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"room": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"full": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"kana": {
"additionalProperties": false,
"type": "object",
"required": [
"prefecture",
"municipality",
"town_area"
],
"properties": {
"prefecture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"municipality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"town_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"romaji": {
"additionalProperties": false,
"type": "object",
"required": [
"prefecture",
"municipality",
"town_area"
],
"properties": {
"prefecture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"municipality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"town_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"codes": {
"additionalProperties": false,
"type": "object",
"required": [
"jis_code",
"machiaza_id",
"residential_block_id",
"residential_id",
"parcel_id"
],
"properties": {
"jis_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"machiaza_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"residential_block_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"residential_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"parcel_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"location": {
"additionalProperties": false,
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"longitude": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
},
"match": {
"additionalProperties": false,
"type": "object",
"required": [
"status",
"score",
"confidence",
"match_level",
"coordinate_level",
"unmatched_text"
],
"properties": {
"status": {
"anyOf": [
{
"const": "matched",
"type": "string"
},
{
"const": "partial",
"type": "string"
},
{
"const": "ambiguous",
"type": "string"
},
{
"const": "not_found",
"type": "string"
}
]
},
"score": {
"minimum": 0,
"maximum": 1,
"type": "number"
},
"confidence": {
"anyOf": [
{
"const": "high",
"type": "string"
},
{
"const": "medium",
"type": "string"
},
{
"const": "low",
"type": "string"
}
]
},
"match_level": {
"anyOf": [
{
"const": "none",
"type": "string"
},
{
"const": "prefecture",
"type": "string"
},
{
"const": "municipality",
"type": "string"
},
{
"const": "machiaza",
"type": "string"
},
{
"const": "machiaza_detail",
"type": "string"
},
{
"const": "block",
"type": "string"
},
{
"const": "residence",
"type": "string"
},
{
"const": "residential_number",
"type": "string"
},
{
"const": "parcel",
"type": "string"
}
]
},
"coordinate_level": {
"anyOf": [
{
"anyOf": [
{
"const": "none",
"type": "string"
},
{
"const": "prefecture",
"type": "string"
},
{
"const": "municipality",
"type": "string"
},
{
"const": "machiaza",
"type": "string"
},
{
"const": "machiaza_detail",
"type": "string"
},
{
"const": "block",
"type": "string"
},
{
"const": "residence",
"type": "string"
},
{
"const": "residential_number",
"type": "string"
},
{
"const": "parcel",
"type": "string"
}
]
},
{
"const": "unavailable",
"type": "string"
}
]
},
"unmatched_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"warnings": {
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"code",
"message",
"hint"
],
"properties": {
"code": {
"anyOf": [
{
"const": "PARTIAL_ADDRESS_MATCH",
"type": "string"
},
{
"const": "MULTIPLE_CANDIDATES",
"type": "string"
},
{
"const": "COORDINATE_LOW_PRECISION",
"type": "string"
},
{
"const": "PREVIEW_DATA_USED",
"type": "string"
},
{
"const": "ROMAJI_UNAVAILABLE",
"type": "string"
},
{
"const": "UNMATCHED_TEXT_REMAINS",
"type": "string"
},
{
"const": "DATA_SOURCE_MISMATCH",
"type": "string"
},
{
"const": "PUBLIC_SUBADDRESS_DATA_NOT_AVAILABLE",
"type": "string"
}
]
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
}
},
"candidates": {
"maxItems": 10,
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"postal_code",
"normalized_address",
"kana",
"codes",
"match_level",
"coordinate_level",
"score"
],
"properties": {
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"normalized_address": {
"additionalProperties": false,
"type": "object",
"required": [
"prefecture",
"municipality",
"town_area",
"kyoto_street",
"chome",
"block",
"lot",
"building_number",
"sub_number",
"building",
"building_name",
"room",
"full"
],
"properties": {
"prefecture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"municipality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"town_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"kyoto_street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chome": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"block": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lot": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sub_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"building_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"room": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"full": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"kana": {
"additionalProperties": false,
"type": "object",
"required": [
"prefecture",
"municipality",
"town_area"
],
"properties": {
"prefecture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"municipality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"town_area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"codes": {
"additionalProperties": false,
"type": "object",
"required": [
"jis_code",
"machiaza_id",
"residential_block_id",
"residential_id",
"parcel_id"
],
"properties": {
"jis_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"machiaza_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"residential_block_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"residential_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"parcel_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"match_level": {
"anyOf": [
{
"const": "none",
"type": "string"
},
{
"const": "prefecture",
"type": "string"
},
{
"const": "municipality",
"type": "string"
},
{
"const": "machiaza",
"type": "string"
},
{
"const": "machiaza_detail",
"type": "string"
},
{
"const": "block",
"type": "string"
},
{
"const": "residence",
"type": "string"
},
{
"const": "residential_number",
"type": "string"
},
{
"const": "parcel",
"type": "string"
}
]
},
"coordinate_level": {
"anyOf": [
{
"anyOf": [
{
"const": "none",
"type": "string"
},
{
"const": "prefecture",
"type": "string"
},
{
"const": "municipality",
"type": "string"
},
{
"const": "machiaza",
"type": "string"
},
{
"const": "machiaza_detail",
"type": "string"
},
{
"const": "block",
"type": "string"
},
{
"const": "residence",
"type": "string"
},
{
"const": "residential_number",
"type": "string"
},
{
"const": "parcel",
"type": "string"
}
]
},
{
"const": "unavailable",
"type": "string"
}
]
},
"score": {
"minimum": 0,
"maximum": 1,
"type": "number"
}
}
}
},
"data_versions": {
"additionalProperties": false,
"type": "object",
"required": [
"japan_post",
"abr",
"abr_database",
"normalizer"
],
"properties": {
"japan_post": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"abr": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"abr_database": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"normalizer": {
"type": "string"
}
}
},
"data_status": {
"additionalProperties": false,
"type": "object",
"required": [
"overall",
"japan_post",
"abr"
],
"properties": {
"overall": {
"anyOf": [
{
"const": "stable",
"type": "string"
},
{
"const": "preview",
"type": "string"
},
{
"const": "partial",
"type": "string"
}
]
},
"japan_post": {
"anyOf": [
{
"const": "stable",
"type": "string"
},
{
"const": "preview",
"type": "string"
},
{
"const": "partial",
"type": "string"
},
{
"const": "unavailable",
"type": "string"
}
]
},
"abr": {
"anyOf": [
{
"const": "stable",
"type": "string"
},
{
"const": "preview",
"type": "string"
},
{
"const": "partial",
"type": "string"
},
{
"const": "unavailable",
"type": "string"
}
]
}
}
}
}
}Match Status
A single result meets the match rules.
Useful components resolved, but the full query did not.
Multiple plausible results are returned as candidates.
The search completed normally with no matching result.
These four outcomes are data results, not transport errors, so they all use HTTP 200.
Confidence
It is a JAPAN API STORE evidence grade, separate from the numeric score.
The grade combines postal-code, prefecture, municipality and town-area agreement; unmatched text; candidate count; ABR match and coordinate levels; and Japan Post / ABR consistency. Use high, medium, or low together with the detailed evidence fields.
Warnings
The contract currently accepts 8 warning codes. Each object contains a machine-readable code, a human-readable message, and an actionable hint.
PARTIAL_ADDRESS_MATCHSome address components matched.Add a postal code, municipality, or town area.
MULTIPLE_CANDIDATESMore than one plausible result exists.Add more address detail and inspect candidates.
COORDINATE_LOW_PRECISIONCoordinates are less precise than the address match.Compare coordinate_level with match_level.
PREVIEW_DATA_USEDA result used preview data below town-area scope.Inspect verification providers before using block, residence, or parcel fields.
ROMAJI_UNAVAILABLERomaji is not available for this result.Use Japanese or kana fields.
UNMATCHED_TEXT_REMAINSPart of the input was not resolved.Inspect unmatched_text for building names or unsupported detail.
DATA_SOURCE_MISMATCHJapan Post and ABR disagree on an address component.Review source versions and candidates before accepting the result.
PUBLIC_SUBADDRESS_DATA_NOT_AVAILABLEOfficial lower-address data is not available for this result.Use the verified town-area result and keep the remaining components unverified.
Errors
400Malformed JSON, invalid request shape, or body too large
401Missing, invalid, or revoked API key
403Authenticated but not permitted
429Usage limit exceeded; inspect Retry-After
500Unexpected internal failure
503Temporary authentication, usage, or data service failure
View error contract
{
"$id": "ApiErrorResponse",
"additionalProperties": false,
"type": "object",
"required": [
"request_id",
"success",
"error"
],
"properties": {
"request_id": {
"type": "string"
},
"success": {
"const": false,
"type": "boolean"
},
"error": {
"additionalProperties": false,
"type": "object",
"required": [
"code",
"message",
"hint"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"hint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
}Candidates
Ambiguous results include at most ten candidates. Candidate objects expose normalized address fields, codes, match and coordinate precision, and an evidence score. Refine the query rather than treating the first candidate as guaranteed.
Data Sources
Japan PostPostal codes, prefectures, municipalities, town areas, and kana from the active approved dataset.
Digital Agency ABRJapan-wide Machiaza matching plus preview residential-address and Ministry of Justice parcel data where available. Lower-address records are stored as integrity-checked regional blocks and loaded only when requested.
JAPAN API STORESafe normalization, source reconciliation, evidence grading, and actionable warnings.
A parcel can be officially verified while its coordinate remains a Machiaza representative point or unavailable. Inspect verification.providers, verified_level, coordinate_level, and location.source together.
View lower-address result examples
{
"parcel": {
"verified_level": "lot",
"addressing_system": "land_lot",
"provider": "moj_cadastral_map_via_digital_agency_abr",
"coordinate_level": "machiaza"
},
"residential": {
"verified_level": "residential_number",
"addressing_system": "residential_address",
"provider": "digital_agency_abr_residential_address",
"coordinate_level": "unavailable"
},
"fallback": {
"verified_level": "machiaza",
"public_data_status": "public_data_not_available",
"unresolved_components": [
"12-3"
]
}
}Data Freshness
Official sources update on different schedules. We do not hide that difference: data_versions reports each version separately, and data_status distinguishes stable, preview, partial, and unavailable source states.
Japanese Address Guide
Japanese addresses use either residential addressing or land-lot addressing. They are not interchangeable. Postal codes can narrow the area but may still map to multiple rows. Kyoto street notation, counties, wards, and omitted prefectures need dedicated handling. Use addressing_system and verified_level rather than inferring the system from punctuation alone.
〒100-0005 東京都千代田区丸の内 1-1Edge Cases
- Hyphenless, 〒-prefixed, and full-width postal codes
- Kanji numerals and variants such as
番地,番,号, and hyphens - Tokyo wards, designated-city wards, and county addresses
- Kyoto street notation and Hokkaido-specific forms
- Parcel-number matches and residential block / building-number matches
- Town-area fallback when no authoritative lower-address record is available
- Prefecture omission and building names
- Ambiguous postal codes and addresses that do not exist
- ABR unavailable with Japan Post partial fallback
FAQ
Is this only a postal code API?
No. It combines postal lookup, address normalization, ABR enrichment, codes, coordinates, match quality, and provenance.
Are coordinates always building-level?
No. Always inspect coordinate_level; it may be less precise than match_level. A verified parcel can still have only a Machiaza representative point.
Can confidence be read as accuracy percentage?
No. Confidence is an evidence grade, not a probability.
Is block, residence, or parcel data guaranteed?
No. The stable v1 scope is generally town area. Lower-level data varies by municipality and is marked preview with provider provenance when used.
Changelog
Added official parcel and residential-address verification across all 47 prefectures where public records are available, with source/verified separation and independent address and coordinate precision.
Updated live Quick Start URLs, organization-wide plan limits, and public data-version reporting.
Documented normalized outcomes, candidates, evidence confidence, warnings, and source status for POST /v1/address/resolve.