Single response success
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),
- "Addresses": a list containing one or more address objects.
Each address object is itself a dictionary containing the following keys:
| Key | Description | Size / Type |
|---|---|---|
| PostalCode | Postal code of the address (here, in UK format). | String (up to 10 characters) |
| City | City name. | String (up to 100 characters) |
| Hamlet | Hamlet or locality. | Optional string |
| SpecialDistribution | Special distribution mention (e.g., PO box, military service, etc.). | Optional string |
| Country | ISO 3166-1 alpha-3 country code (e.g., "GBR" for the United Kingdom). | Fixed string (3 characters) |
| StateCode | State or administrative region code (often empty for non-federal countries). | Optional string (0–10 characters) |
| SubLocality | Sub-locality or neighborhood (e.g., Chelsea, Soho). | Optional string |
| CityId | Internal or database identifier for the city. | String or integer (variable) |
| Input | Original user input used for the search or normalization. | String (up to 255 characters) |
| Label | Full formatted address label (user display). | String (up to 255 characters) |
| AdditionalAddress | Address complement (e.g., apartment, building, residence). | String (up to 255 characters) |
| StreetNumber | Street number (e.g., "12"). | String (up to 10 characters) |
| StreetType | Street type (e.g., "Street", "Avenue", "Road"). | String (up to 50 characters) |
| Street | Street name. | String (up to 100 characters) |
| StreetId | Unique internal street identifier (often concatenated with the postal code). | String (variable, up to 50 characters) |
| IsValidStreetNumber | Validity indicator for the street number (1 = valid, 0 = invalid). | Integer (0 or 1) |
| StreetNumberListCount | Number of available street numbers for this street. | Integer |
| StreetNumberList | List of available street numbers (if any). | String or array |
| StreetNumberOnly | Isolated street number without complement. | Optional string |
| StateLabel | Full name of the state or region. | Optional string |
| AdministrativeArea | Administrative subdivision above the city. | Optional string |
| Suburb | Suburb or district. | Optional string |
| Company | Company name associated with the address. | Optional string |
| Latitude | Geographic coordinate (latitude). | String or number (e.g., “51.4988”) |
| Longitude | Geographic coordinate (longitude). | String or number (e.g., “-0.1337”) |
Example:
{
"Found": 1,
"Addresses": [
{
"PostalCode": "108-6390",
"City": "港区",
"Hamlet": "",
"SpecialDistribution": "",
"Country": "JPN",
"StateCode": "13",
"SubLocality": "",
"CityId": "402573",
"Input": "108-6390",
"Label": "〒108-6390 東京都港区三田",
"AdditionalAddress": "",
"StreetNumber": "",
"StreetType": "",
"Street": "三田",
"StreetId": "558203",
"IsValidStreetNumber": 1,
"StreetNumberListCount": 0,
"StreetNumberList": "",
"StreetNumberOnly": "",
"StateLabel": "東京都",
"AdministrativeArea": "港区",
"Suburb": "",
"Company": "",
"Latitude": "",
"Longitude": ""
}
]
}
Single response error
| Error type | Request | Response type |
| Missing “Licence” parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?Address=UB96NS&Country=GBR | {"status": 400, "message": "Missing parameters", "details": "Licence", "error": "bad request"} |
| Empty “Licence” parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?Address=UB96NS&Country=GBR&Licence= | {"status": 400, "message": "Licence must be filled", "details": "Empty", "error": "bad request"} |
| Incorrect licence number | https://{SERVER_ADDRESS}/{VERSION}/single/?Address=UB96NS&Country=GBR&Licence={WRONG LICENSE} | {"status": 401, "message": "Your licence is not allowed to cover this functionnality", "details": "{WRONG KucENCE}", "error": "unauthorized_client"} |
| Missing “Address” parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?&Country=GBR&Licence={LICENSE} | {"status": 400, "message": "Missing parameters", "details": "Address", "error": "bad request"} |
| Missing “Country” parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?Address=a&Licence={LICENSE} | {"status": 400, "message": "Missing parameters", "details": "Country", "error": "bad request"} |
| Empty “Address” parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?Address=a&Country=&Licence={LICENSE} | {"status": 400, "message": "Country must be filled", "details": "Empty", "error": "bad request"} |
| Empty “Country” parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?Address=a&Country=&Licence={LICENSE} | {"status": 400, "message": "Country must be filled", "details": "Empty", "error": "bad request"} |
| Error on a parameter | https://{SERVER_ADDRESS}/{VERSION}/single/?Adress=a&Country=GBR&Licence={LICENSE} | {"status": 400, "message": "Missing parameters", "details": "Address", "error": "bad request"} |
Related to