Use the /single/ endpoint to return address suggestions from a single free-form address input. Once the user selects an address, optionally call /compl/ to retrieve building or apartment complement details.
GET request
Endpoint
https://{SERVER_ADDRESS}/{VERSION}/single/?Address={INPUT}&Length={LENGTH}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}&Limit={NB}&Version=1&Langue={LANGUAGE}&Filter={FILTER}Replace the values in braces with your own information.
| Parameter | Value | Description | Mandatory/Optional |
|---|---|---|---|
| SERVER_ADDRESS | {SERVER_ADDRESS} | Address of the DQE server that will process the data. | Mandatory |
| VERSION | {VERSION} | Version of the API (e.g. v1). | Mandatory |
| Licence | {LICENCE_CODE} | Licence code assigned to your account or token generated by oauth2. | Mandatory |
| Address | {INPUT} | User input. | Mandatory |
| Country | {COUNTRY_CODE} | ISO 3-letter country code. | Mandatory |
| Length | {LENGTH} | Character limit for the address. Works only on Latin addresses. | Optional. Default: 38. Recommended minimum: 32. |
| Limit | {NB} | Limits the number of returned responses. Maximum: 20. | Optional. Default: 20. |
| Version | 1 | Allows the street type to be returned in the response. Without this parameter, the street type is not sent in the dedicated key. | Optional |
| Langue | {LANGUAGE} | For Japan only: JP Kanji, JK Katakana, EN English. | Optional |
| Filter | {FILTER} | France only. 1: all addresses. 2: no Cedex. 3: Cedex only. | Optional |
POST request
Endpoint
https://{SERVER_ADDRESS}/{VERSION}/single/Add the parameters below in the request body using x-www-form-urlencoded.
| Parameter | Value | Description | Mandatory/Optional |
|---|---|---|---|
| Licence | {LICENCE_CODE} | Licence code assigned to your account or token generated by oauth2. | Mandatory |
| Address | {INPUT} | User input. | Mandatory |
| Country | {COUNTRY_CODE} | ISO 3-letter country code. | Mandatory |
| Length | {LENGTH} | Character limit for the address. | Optional. Default: 38. Recommended minimum: 32. |
| Limit | {NB} | Limits the number of returned responses. Maximum: 20. | Optional. Default: 20. |
| Version | 1 | Allows the street type to be returned in the response. | Optional |
| Langue | {LANGUAGE} | For Japan only: JP Kanji, JK Katakana, EN English. | Optional |
| Filter | {FILTER} | France only. 1: all; 2: no Cedex; 3: Cedex only. | Optional |
Response
Success response
The JSON response contains a Found count and an Addresses array. Each element contains one address suggestion.
{
"Found": 2,
"Addresses": [
{
"PostalCode": "75008",
"City": "Paris 8e Arrondissement",
"Hamlet": "",
"SpecialDistribution": "",
"Country": "FRA",
"StateCode": "75",
"SubLocality": "",
"CityId": "75056",
"Input": "12 AV DES CHAMPS ELYSEES",
"Label": "12 Av des Champs-Elysees 75008 Paris 8e Arrondissement",
"AdditionalAddress": "",
"StreetNumber": "12",
"StreetType": "Av",
"Street": "des Champs-Elysees",
"StreetId": "750080153",
"IsValidStreetNumber": true,
"StreetNumberListCount": 148,
"StreetNumberList": "1,3,5,...",
"StreetNumberOnly": "12",
"StateLabel": "Paris",
"AdministrativeArea": "Ile-de-France",
"Suburb": "",
"Company": "",
"Latitude": null,
"Longitude": null
}
]
}| Key | Description | Size / Type |
|---|---|---|
| PostalCode | Postal code of the address. | String (up to 10 characters) |
| City | City name. | String (up to 100 characters) |
| Hamlet | Hamlet or locality. | Optional string |
| SpecialDistribution | Special distribution mention. | Optional string |
| Country | ISO 3166-1 alpha-3 country code. | Fixed string (3 characters) |
| StateCode | State or administrative region code. | Optional string |
| SubLocality | Sub-locality or neighborhood. | Optional string |
| CityId | Internal identifier for the city. | String or integer |
| Input | Original user input. | String (up to 255 characters) |
| Label | Formatted address label. | String (up to 255 characters) |
| AdditionalAddress | Address complement. | String (up to 255 characters) |
| StreetNumber | Street number. | String (up to 10 characters) |
| StreetType | Street type. | String (up to 50 characters) |
| Street | Street name. | String (up to 100 characters) |
| StreetId | Unique street identifier. | String |
| IsValidStreetNumber | Street number validity indicator. | Integer |
| StreetNumberListCount | Number of available street numbers. | Integer |
| StreetNumberList | Available street numbers. | String or array |
| StreetNumberOnly | Street number without complement. | Optional string |
| StateLabel | Full state or region name. | 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 | Latitude coordinate. | String or number |
| Longitude | Longitude coordinate. | String or number |
Error response
Errors are returned as JSON in the following format:
{
"status": 401,
"message": "Unauthorized",
"details": "Invalid licence code",
"error": "Unauthorized"
}| 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 functionality","details":"{WRONG_LICENSE}","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 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"} |