CP Response Success
The JSON response is a dictionary whose keys are the numbers from 1 to n and where each element is itself a dictionary containing the following keys :
- If the postal code does not refer to a street or a company :
Request example :
https://{SERVER_ADDRESS}/CP/?CodePostal=75015&Alpha=True&Instance=0&Pays=FRA&Licence={LICENCE_CODE}
| Key | Value | Always in JSON? | Format if in JSON response |
| Province | Region where the city is located. Type will depend on the country where the search is performed. Ex for USA: State’s 2 letter code will be sent here | Yes | STRING(50) |
| IDLocalite | Unique code for each city (INSEE code for France) | Yes | STRING(20) |
| Pays | ISO country code | Yes | STRING(3) |
| Instance | Number passed as a parameter during the call and returned in the response | Yes | STRING(3) |
| CodePostal | City Zip Code | Yes | STRING(10) |
| SousLocalite | Additional information on city | Yes | STRING(50) |
| LieuDit | Dependent locality if applicable | Yes | STRING(50) |
| Localite | City name | Yes | STRING(50) |
| Latitude | Latitude code of the centre of the locality | Yes | DECIMAL(18) |
| Longitude | Longitude code of the centre of the locality | Yes | DECIMAL(18) |
| IDVoie | Unique number to designate the street (if not empty it means that the postal code references a street) | Yes | STRING(20) |
| NbNumero | Number of numbers in the street | Yes | STRING(4) |
| Voie | Only if IDVoie is filled | No | STRING(50) |
| Numero | Empty | Yes | Empty |
| ListeNumero | Empty | Yes | STRING(1024) |
| TypeVoie | Empty | Yes | Empty |
| Complement | Additional address information | Yes | STRING(255) |
| Entreprise | Company name | Yes | STRING(255) |
| Cedex | Indicates whether it is a cedex or not (1 = CEDEX, 0 = not CEDEX) | Yes | STRING(1) |
Example:
{
"1": {
"Province": "IL",
"IDLocalite": "60007",
"NbNumero": "",
"Pays": "USA",
"IDVoie": "",
"Cedex": "0",
"Numero": "",
"TypeVoie": "",
"Instance": "",
"ListeNumero": "",
"CodePostal": "60007",
"SousLocalite": "",
"LieuDit": "",
"Latitude": "",
"Localite": "Elk Grove Village",
"Longitude": "",
"Complement": "",
"Entreprise": ""
}
}
- If the postal code refers to a street or a company :
Request example :
https://{SERVER_ADDRESS}/CP/?CodePostal=92390&Alpha=True&Instance=0&Pays=FRA&Licence={LICENCE_CODE}
| Field | Meaning | Always in JSON? | Type / Format |
|---|---|---|---|
| Province | Region/Province where the city is located (here *) | Yes | STRING(50) |
| IDLocalite | Unique code for the city (e.g. INSEE for France) | Yes | STRING(20) |
| Pays | ISO country code | Yes | STRING(3) |
| Instance | Parameter passed in request and returned | Yes | STRING(3) |
| CodePostal | Zip / Postal code | Yes | STRING(10) |
| SousLocalite | Additional locality info | Yes | STRING(50) |
| LieuDit | Dependent locality / place name | Yes | STRING(50) |
| Localite | City name / label | Yes | STRING(50) |
| Latitude | Latitude of locality center | Yes | DECIMAL(18) (often returned as STRING in your sample) |
| Longitude | Longitude of locality center | Yes | DECIMAL(18) (often returned as STRING in your sample) |
| IDVoie | Unique identifier for the street | Yes | STRING(20) (alphanumeric possible, e.g. W2503962) |
| Voie | Street name | Conditional (only if IDVoie is not empty) | STRING(50) |
| NbNumero | Count of house numbers on the street | Yes | STRING(4) (numeric in practice) |
| ListeNumero | List of house numbers (semicolon-separated) | Yes | STRING(1024) |
| Numero | House number (empty in sample) | Yes | STRING (can be empty) |
| TypeVoie | Street type (empty in 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) |
Example:
{
"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": ""
}
}CP Response Error
| Error type | Request | Response type |
| Missing “Licence” parameter | https://{SERVER_ADDRESS}/CP/?CodePostal=77777&Alpha=True&Instance=0&Pays=FRA | Empty response |
| Empty “Licence” parameter | https://{SERVER_ADDRESS}/CP/?CodePostal=77777&Alpha=True&Instance=0&Pays=FRA&Licence= | Empty response |
| Incorrect Licence number (expired, out of scope, nonexistent) | https://{SERVER_ADDRESS}/CP/?CodePostal=77777&Alpha=True&Instance=0&Pays=FRA&Licence={INCORRECT_LICENCE_CODE} | Empty response |
| Missing “CodePostal”parameter | https://{SERVER_ADDRESS}/CP/?Alpha=True&Instance=0&Pays=FRA&Licence={LICENCE_CODE} | 400 Bad Request Error |
| Error on a parameter | https://{SERVER_ADDRESS}/CP/?CdePostal=77777&Pays=FRA&Alpha=true&Licence={LICENCE_CODE} | 400 Bad Request Error |
Related to