API - Description - Address - CP - Response

Support DQE
Support DQE
  • Updated

This page describes the JSON response returned by the /CP/ endpoint used in Funnel mode.

Related Address documentation:

CP response success

The JSON response is a dictionary whose keys are numbered from 1 to n. Each element contains locality, postal code, street, company, and geolocation information depending on the returned result.

Case 1: 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. The type depends on the country where the search is performed. For the USA, this field contains the 2-letter state code. Yes STRING(50)
IDLocalite Unique code for each city. For France, this is the INSEE code. Yes STRING(20)
Pays ISO country code. Yes STRING(3)
Instance Value passed as a parameter during the call and returned in the response. Yes STRING(3)
CodePostal City ZIP or postal code. Yes STRING(10)
SousLocalite Additional information on the city. Yes STRING(50)
LieuDit Dependent locality if applicable. Yes STRING(50)
Localite City name. Yes STRING(50)
Latitude Latitude of the centre of the locality. Yes DECIMAL(18)
Longitude Longitude of the centre of the locality. Yes DECIMAL(18)
IDVoie Unique identifier for the street. If not empty, the postal code references a street. Yes STRING(20)
NbNumero Number of numbers in the street. Yes STRING(4)
Voie Street name. Returned only if IDVoie is filled. No STRING(50)
Numero Street number. Empty in this case. Yes Empty
ListeNumero List of street numbers. Empty in this case. Yes STRING(1024)
TypeVoie Street type. Empty in this case. Yes Empty
Complement Additional address information. Yes STRING(255)
Entreprise Company name. Yes STRING(255)
Cedex Indicates whether it is a Cedex: 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": ""
  }
}

Case 2: the postal code refers to a street or a company

The streets are returned in /CP only if the postal code contains 100 streets or fewer in the reference database. This behavior is specific to France.

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 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)

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, or 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

Was this article helpful?

0 out of 0 found this helpful