Success funnelpostcode answer
The JSON response is a dictionary (object) containing two main keys:
- "Found": an integer indicating the number of addresses found (e.g., 0 or 1),
- "PostalCodes": a list containing one or more address objects.
Each PostalCodes object is itself a dictionary containing the following keys:
| Field | Meaning | Always in JSON? | Type / Format |
|---|---|---|---|
| PostalCode | Postal / ZIP code | Yes | STRING(10–20) (example includes hyphen) |
| City | City name | Yes | STRING(50) |
| Hamlet | Hamlet / dependent locality | Yes | STRING(50) (can be empty) |
| SpecialDistribution | Special distribution flag | Yes | STRING(1) (“0/1” style in sample) |
| Country | ISO country code | Yes | STRING(3) |
| AdministrativeArea | Administrative area (may equal city/ward) | Yes | STRING(50) |
| StateLabel | State/Prefecture label | Yes | STRING(50) |
| StateCode | State/Prefecture code | Yes | STRING(10) (numeric in practice, string in sample) |
| SubLocality | Sub-locality info | Yes | STRING(50) (can be empty) |
| CityId | Unique identifier for the city + postal code | Yes | STRING(50) |
| Latitude | Latitude | Yes | DECIMAL(18) (empty string possible in sample) |
| Longitude | Longitude | Yes | DECIMAL(18) (empty string possible in sample) |
| Informations | Nested address details | Yes | OBJECT <Informations> |
Informations object :
| Field | Meaning | Always in JSON? | Type / Format |
|---|---|---|---|
| AdditionalAddress | Extra address line | Yes | STRING(255) (can be empty) |
| AdditionalAddress_2 | Extra address line 2 | Yes | STRING(255) (can be empty) |
| StreetNumberList | List of street numbers | Yes | STRING(1024) (can be empty; separator not specified) |
| StreetType | Street type | Yes | STRING(50) (can be empty) |
| Street | Street name | Yes | STRING(255) (can be empty) |
| Suburb | Suburb / district | Yes | STRING(255) (can be empty) |
| StreetId | Street identifier | Yes | STRING(20) (can be empty) |
| Company | Company name | Yes | STRING(255) (can be empty) |
Example:
{
"Found": 1,
"PostalCodes": [
{
"PostalCode": "108-6390",
"City": "港区",
"Hamlet": "",
"SpecialDistribution": "0",
"Country": "JPN",
"AdministrativeArea": "港区",
"StateLabel": "東京都",
"StateCode": "13",
"SubLocality": "",
"CityId": "402573_1086390",
"Latitude": "",
"Longitude": "",
"Informations": {
"AdditionalAddress": "",
"AdditionalAddress_2": "",
"StreetNumberList": "",
"StreetType": "",
"Street": "",
"Suburb": "",
"StreetId": "",
"Company": ""
}
}
]
}
Error
| Error type | Response type |
| Missing mandatory parameter | { "status": 400, "message": "Missing parameters", "details": "PostalCode", "error": "bad request" } |
| Country value is not ISO3 | {"status": 400, "message": "Country doesn't exist", "details": "JPNde", "error": "bad request"} |
| Wrong license value | {"status": 401, "message": "Your licence is not allowed to cover this functionnality", "details": "WRONG LICENSE", "error": "unauthorized_client"} |
Related to