Use the /CP/ endpoint as the first step in the funnel address search flow. Search for localities by postal code or city name. Then pass the returned IDLocalite to /ADR/ to search streets within the selected city.
GET request
Endpoint
https://{SERVER_ADDRESS}/CP/?CodePostal={POSTAL_CODE}&Alpha=True&Instance={VALUE}&Pays={COUNTRY_CODE}&Etendue=Y&Licence={LICENCE_CODE}&NbMax={NB_MAX}&Filter={FILTER}&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 |
| CodePostal | {POSTAL_CODE} |
Postal code or city name input. | Mandatory |
| Pays | {COUNTRY_CODE} |
ISO 3-letter country code. | Mandatory |
| Alpha | True |
Must always be set to True. |
Mandatory |
| Instance | {VALUE} |
Allows you to pass a value during the call, returned in the response. | Optional |
| Etendue | Y |
France and Belgium only. Enables search with as few as 2 digits entered. | Optional |
| NbMax | {NB_MAX} |
Limits the number of returned responses. | Optional |
| Filter | {FILTER} |
Filters returned address types. 1: postal + PO box. 2: postal + street. 3: postal only. 4: one per postal+city (Malaysia only). |
Optional |
| Langue | {LANGUAGE} |
For Japan only: JP Kanji, JK Katakana, EN English. |
Optional |
POST request
Endpoint
https://{SERVER_ADDRESS}/CP/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 |
| CodePostal | {POSTAL_CODE} |
Postal code or city name input. | Mandatory |
| Pays | {COUNTRY_CODE} |
ISO 3-letter country code. | Mandatory |
| Alpha | True |
Must always be set to True. |
Mandatory |
| Instance | {VALUE} |
Allows you to pass a value during the call. | Optional |
| Etendue | Y |
France and Belgium only. Enables search with as few as 2 digits. | Optional |
| NbMax | {NB_MAX} |
Limits the number of returned responses. | Optional |
| Filter | {FILTER} |
1: postal + PO box. 2: postal + street. 3: postal only. 4: one per postal+city (Malaysia). |
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 locality suggestion. For France, when the postal code refers directly to a street or company, up to 100 streets may be returned with an IDVoie value.
{
"42": {
"Province": "*",
"IDLocalite": "92048",
"NbNumero": "14",
"Pays": "FRA",
"IDVoie": "1750416",
"Voie": "RUE DE LA PEPINIERE",
"Cedex": "0",
"Numero": "",
"TypeVoie": "",
"Instance": "0",
"ListeNumero": "2;2B;3;4;5;6;7;8;10;12;14;16;18;20",
"CodePostal": "92360",
"SousLocalite": "",
"LieuDit": "",
"Latitude": "48.8130414978102",
"Localite": "MEUDON (LD. MEUDON LA FORET)",
"Longitude": "2.23855375105306",
"Complement": "",
"Entreprise": ""
}
}| Field | Meaning | Always in JSON? | Type / Format |
|---|---|---|---|
| Province | Region or province where the city is located. | Yes | STRING(50) |
| IDLocalite | Unique code for the city. For France, this is the INSEE code. | Yes | STRING(20) |
| Pays | ISO country code. | Yes | STRING(3) |
| Instance | Value passed in the request and returned in the response. | Yes | STRING(3) |
| CodePostal | ZIP or postal code. | Yes | STRING(10) |
| SousLocalite | Additional locality information. | Yes | STRING(50) |
| LieuDit | Dependent locality or place name. | Yes | STRING(50) |
| Localite | City name or label. | Yes | STRING(50) |
| Latitude | Latitude of the locality center. | Yes | DECIMAL(18), often returned as a string |
| Longitude | Longitude of the locality center. | Yes | DECIMAL(18), often returned as a string |
| IDVoie | Unique identifier for the street. | Yes | STRING(20), alphanumeric possible |
| Voie | Street name. | Conditional, only if IDVoie is not empty |
STRING(50) |
| NbNumero | Number of house numbers on the street. | Yes | STRING(4), numeric in practice |
| ListeNumero | List of house numbers, separated by semicolons. | Yes | STRING(1024) |
| Numero | House number. Empty in the sample. | Yes | STRING, can be empty |
| TypeVoie | Street type. Empty in the sample. | Yes | STRING, can be empty |
| Complement | Additional address details. | Yes | STRING(255) |
| Entreprise | Company name. | Yes | STRING(255) |
| Cedex | Cedex flag: 1 = Cedex, 0 = not Cedex. |
Yes | STRING(1) |
Error response
| Error type | Response type |
|---|---|
Missing or incorrect Licence parameter |
Empty response |
Missing CodePostal parameter |
400 Bad Request |
| Parameter error | 400 Bad Request |