Use the /ADR/ endpoint as the second step in the funnel address search flow. Search for streets within a city using the IDLocalite returned by /CP/. Then pass the returned IDVoie and IDNum to /COMPL/ to retrieve address complements.
GET request
Endpoint
https://{SERVER_ADDRESS}/ADR/?IDLocalite={CITY_ID}&Adresse={ADDRESS}&Instance={VALUE}&Pays={COUNTRY_CODE}&Taille={LENGTH}&Version=1.1&Licence={LICENCE_CODE}&Langue={LANGUAGE}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 |
| Licence | {LICENCE_CODE} | Licence code assigned to your account or token generated by oauth2. | Mandatory |
| IDLocalite | {CITY_ID} | City ID returned by /CP/. | Mandatory |
| Adresse | {ADDRESS} | User input for the street name. | Mandatory |
| Pays | {COUNTRY_CODE} | ISO 3-letter country code. | Mandatory |
| Taille | {LENGTH} | Character limit for the address. Works only on Latin addresses. | Optional. Default: 38. Recommended minimum: 32. |
| Instance | {VALUE} | Allows you to pass a value during the call, returned in the response. | Optional |
| Version | 1.1 | Populates the LieuDit field for small towns in France. | Optional |
| Langue | {LANGUAGE} | For Japan only: JP Kanji, JK Katakana, EN English. | Optional |
POST request
Endpoint
https://{SERVER_ADDRESS}/ADR/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 |
| IDLocalite | {CITY_ID} | City ID returned by /CP/. | Mandatory |
| Adresse | {ADDRESS} | User input for the street name. | Mandatory |
| Pays | {COUNTRY_CODE} | ISO 3-letter country code. | Mandatory |
| Taille | {LENGTH} | Character limit for the address. | Optional. Default: 38. Recommended minimum: 32. |
| Instance | {VALUE} | Allows you to pass a value during the call. | Optional |
| Version | 1.1 | Populates the LieuDit field for small towns in France. | Optional |
| Langue | {LANGUAGE} | For Japan only: JP Kanji, JK Katakana, EN English. | Optional |
Response
Success response
The JSON response is a dictionary whose keys are numbered from 1 to n. Each element contains one street suggestion.
{
"1": {
"label": "Retkeilijänkatu|00980 Helsinki",
"valid_num": 0,
"Num": "",
"Numero": "",
"ListeNumero": "1;2;3;4;5;6;7A;7B;8;9;10;11;12;13;15;16;18",
"Nbnumero": 17,
"NbNumero": 17,
"NumSeul": "",
"Saisie": "Retkeilijänkatu",
"Pays": "FIN",
"Complement": "",
"Voie": "Retkeilijänkatu",
"CodeVoie": "225242",
"IDVoie": "225242",
"IDLocalite": "4265",
"Instance": 1,
"CodePostal": "00980",
"Localite": "Helsinki",
"Province": "Uusimaa",
"LieuDit": "",
"Longitude": "",
"Latitude": "",
"Region1": "Uusimaa",
"Region2": "",
"Region3": "",
"Suburb": "",
"TypeVoie": ""
}
}| Key | Value | In JSON response for all countries? | Format if in JSON response |
|---|---|---|---|
| Saisie | Text input passed in the parameter and used to search the street. | Yes | STRING(255) |
| IDLocalite | Unique code for each city. INSEE code for France. | Yes | STRING(20) |
| Pays | ISO country code. | Yes | STRING(3) |
| CodePostal | City postal code. | Yes | STRING(10) |
| Localite | Name of the city. | Yes | STRING(50) |
| Roudis | Roudis code (France only). | No | NA |
| Instance | Value passed in the request and returned in the response. | Yes | STRING(3) |
| Cedex | Indicates whether the result is a Cedex: 1 = Cedex, 0 = not Cedex. | No | STRING(1) |
| Latitude | Latitude of the centre of the locality. | No | DECIMAL(8) |
| Longitude | Longitude of the centre of the locality. | No | DECIMAL(8) |
| IDVoie | Unique number identifying the street. | Yes | STRING(20) |
| Voie | Street name. | Yes | STRING(50) |
| Numero | Street number with complement (bis, ter, etc.). | Yes | STRING(10) |
| Num | Street number with complement (bis, ter, etc.). | No | STRING(10) |
| Nbnumero | Number of house numbers in the street. | No | STRING(4) |
| NbNumero | Number of house numbers in the street. | Yes | STRING(4) |
| ListeNumero | List of available house numbers in the street. | Yes | STRING(1024) |
| TypeVoie | Street type (street, avenue, etc.). | No | STRING(20) |
| CodeVoie | Unique number identifying the street. | Yes | STRING(20) |
| Complement | Additional address information. | No | STRING(150) |
| Complement2 | Additional address information 2. | No | STRING(50) |
| LieuDit | Dependent locality if applicable. | Yes | STRING(50) |
| Entreprise | Company name. | No | STRING(255) |
| label | Label displayed for auto-completion. | No | STRING(255) |
| Province | Region where the city is located. | No | STRING(50) |
| Region1 | Region. | No | STRING(50) |
| Region2 | County. | No | STRING(50) |
| Region3 | County. | No | STRING(50) |
| Suburb | Suburb. | No | STRING(50) |
| Thoroughfare | Dependent street. UK only. | No | UK only |
| valid_num | 1: the number exists in the street. 0: the number does not exist in the street. | No | INTEGER(1) |
Error response
| Error type | Request | Response type |
|---|---|---|
Missing Licence parameter | https://{SERVER_ADDRESS}/ADR/?IDLocalite=13201&Adresse=post&Instance=0&Pays=FRA&Taille=38&Version=1.1 | Empty response |
Empty Licence parameter | https://{SERVER_ADDRESS}/ADR/?IDLocalite=13201&Adresse=post&Instance=0&Pays=FRA&Taille=38&Licence=&Version=1.1 | Empty response |
| Incorrect licence number | https://{SERVER_ADDRESS}/ADR/?IDLocalite=13201&Adresse=post&Instance=0&Pays=FRA&Taille=38&Licence={INCORRECT_LICENCE_CODE}&Version=1.1 | Empty response |
Missing IDLocalite parameter | https://{SERVER_ADDRESS}/ADR/?Adresse=post&Instance=0&Pays=FRA&Taille=38&Licence={LICENCE_CODE}&Version=1.1 | 400 Bad Request error |
Missing Adresse parameter | https://{SERVER_ADDRESS}/ADR/?IDLocalite=13201&Instance=0&Pays=FRA&Taille=38&Licence={LICENCE_CODE}&Version=1.1 | 400 Bad Request error |
Missing Pays parameter | https://{SERVER_ADDRESS}/ADR/?IDLocalite=13201&Adresse=post&Instance=0&Taille=38&Licence={LICENCE_CODE}&Version=1.1 | 400 Bad Request error |
| Error on a parameter | https://{SERVER_ADDRESS}/ADR/?Aresse=PYREN&IDLocalite=75120&Pays=FRA&Taille=38&Licence={LICENCE_CODE} | 400 Bad Request error |