Use the /SINGLEV2/ endpoint to return address suggestions from a single free-form address input. Once the user selects an address, optionally call /COMPLV2/ to retrieve building or apartment complement details.
GET request
Endpoint
https://{SERVER_ADDRESS}/SINGLEV2/?Adresse={INPUT}&Taille={LENGTH}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}&NbMax={NB}&Version=1&Instance={VALUE}&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 |
| Licence | {LICENCE_CODE} | Licence code assigned to your account or token generated by oauth2. | Mandatory |
| Adresse | {INPUT} | User input. | 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. |
| NbMax | {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 |
| Instance | {VALUE} | Allows you to pass a value during the call, returned in the response. | 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}/SINGLEV2/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 |
| Adresse | {INPUT} | User input. | 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. |
| NbMax | {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 |
| Instance | {VALUE} | Allows you to pass a value during the call. | 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 is a dictionary whose keys are numbered from 1 to n. Each element contains one address suggestion.
{
"1": {
"Instance": "",
"IDLocalite": "75056",
"CodePostal": "75008",
"Localite": "PARIS 8",
"SousLocalite": "",
"Pays": "FRA",
"LieuDit": "",
"Latitude": "",
"Longitude": "",
"IDVoie": "750080153",
"Label": "12 AV DES CHAMPS ELYSEES 75008 PARIS 8",
"Numero": "12",
"Num": "12",
"NbNumero": "148",
"valid_num": "1",
"NumSeul": "12",
"ListeNumero": "1,3,5,...",
"TypeVoie": "AV",
"Voie": "DES CHAMPS ELYSEES",
"Complement": "",
"Saisie": "12 AV DES CHAMPS ELYSEES"
}
}| Key | Value | France | International |
|---|---|---|---|
| Instance | Value passed as a parameter during the call and returned in the response. | STRING(3) | STRING(3) |
| Province | Region where the city is located. For the USA, this field contains the 2-letter state code. | Not available | STRING(50) |
| IDLocalite | Unique code for each city. INSEE code for France. | STRING(20) | STRING(20) |
| CodePostal | City postal code. | STRING(10) | STRING(10) |
| Localite | City name. | STRING(38) | STRING(50) |
| SousLocalite | Used for countries other than France. | Empty | STRING(50) |
| Pays | ISO country code. | STRING(3) | STRING(3) |
| LieuDit | Dependent locality if applicable. | STRING(38) | Empty |
| Latitude | Latitude of the address. | Not available | Empty |
| Longitude | Longitude of the address. | Not available | Empty |
| IDVoie or CodeVoie | Unique number identifying the street. | STRING(20) | STRING(20) |
| Label | Label displayed for auto-completion. A street number in brackets indicates that the street number does not exist. | STRING(255) | STRING(255) |
| Region1 | Official region. | Not available | STRING(50) |
| Region2 | County. | Not available | STRING(50) |
| Region3 | County. | Not available | STRING(50) |
| Region4 | Other region information. | Not available | STRING(50) |
| Numero | Street number with complement. | STRING(38) | STRING(38) |
| Num | Street number with complement. | STRING(4) | STRING(4) |
| NbNumero or Nbnumero | Number of numbers in the street. | INTEGER(4) | INTEGER(4) |
| valid_num | 1: the number exists in the street. 0: the number does not exist. | INTEGER(1) | Not available |
| NumSeul | Street number without the number complement. | STRING(4) | STRING(4) |
| ListeNumero | List of available numbers in the street. | STRING(1024) | STRING(1024) |
| TypeVoie | Street type. Returned when Version=1 is set. | STRING(20) | Not available |
| Voie | Street name. | STRING(38) | STRING(150) |
| Suburb | Suburb. | Not available | STRING(50) |
| Complement | Additional address information. | Empty | STRING(50) |
| Complement2 | Additional address information 2. | Not available | STRING(50) |
| Saisie | Text input used to search the street. | STRING(255) | STRING(255) |
| Entreprise | Company name. | STRING(38) | UK only |
| Thoroughfare | Dependent street. | Not available | UK only |
Error response
| Error type | Response type |
|---|---|
Missing or incorrect Licence parameter | Empty response |
Missing Adresse parameter | 400 Bad Request |
Missing Pays parameter | 400 Bad Request |
| Error on a parameter name | 400 Bad Request |
Related to