Address API - Autocomplete from a postcode (Classic)

Funnel autocomplete - Standard API

Three-step address autocomplete using the classic API. CP finds matching cities from postal code or city name input; ADR returns streets within the selected city; COMPL retrieves sub-building options after street selection.

Three-step autocomplete flow

Step 1/CP/City search → Step 2/ADR/Street search → Step 3/COMPL/Building & apartment details

Output casing - The casing follows the postal norm of the country concerned.

City search (CP)

First step of the funnel approach. Returns matching cities and postal codes from a partial postal code or city name input. The IDLocalite from each result feeds the next step: ADR.

Jump to Request Parameters Response Example Errors ▶ Test the API

Request

CP supports both GET and POST.

{SERVER_ADDRESS} and {LICENCE_CODE} are provided by DQE upon account creation. Contact your DQE account manager to obtain these credentials.

GET POST

GEThttps://{SERVER_ADDRESS}/CP/?CodePostal={POSTAL_CODE}&Alpha=True&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL example

France - Search by postal code

curl "https://{SERVER_ADDRESS}/CP/?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/CP/

Send all parameters in the request body using Content-Type: application/x-www-form-urlencoded. The server address remains in the URL.

cURL example

curl -X POST "https://{SERVER_ADDRESS}/CP/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "CodePostal=75008" \
  -d "Alpha=True" \
  -d "Pays=FRA" \
  -d "Licence={LICENCE_CODE}"

Parameters

Parameter	Value	Description	Mand / Opt
Licence	`{LICENCE_CODE}`	Your DQE licence key or OAuth2 token. Contact support if you do not yet have one.	Mandatory
CodePostal	`{POSTAL_CODE}`	Postal code or city name input.	Mandatory
Pays	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Alpha	`True`	Always send `True`. Required parameter.	Mandatory
Instance	`{INSTANCE}`	Not echoed back in results for this endpoint - safe to omit.	Optional
Etendue	`Y` or `N`	Enables search from just 2 characters in the postal code input. Default: `N`.	Optional
NbMax	`{NB}`	Maximum number of locality suggestions returned.	Optional
Filter	`{FILTER}`	Controls the type of results returned. When omitted, the response includes postal codes, streets (where available) and CEDEX entries. `1` = postal code & CEDEX only · `2` = postal code & street (no CEDEX) · `3` = postal code only · `4` = one suggestion per postal code & city (Malaysia only)	Optional
Langue	`{LANGUAGE}`	Filters results by language/script. JPN: `JP` = Kanji · `JK` = Katakana · `EN` = Romanized. HKG: `EN` · `ZH`. THA: `EN` · `TH`. See Language guide.	Optional

France & Belgium: postal codes may map to multiple municipalities (fragmented grouping). CP will return one result row per municipality.

Response

On success, the API returns a JSON object. Keys are rank numbers from "1" to "n", each mapping to a dictionary of address fields.

Variable response schema - When IDVoie is populated, Voie appears in the JSON. When only a city is returned, Voie is absent. Use a non-empty IDVoie to detect which schema applies.

Result ordering - Results are ranked by relevance, not by ascending postal code. When an exact postal code is entered and maps to a single city, one result is returned. When a partial postal code is entered with Etendue=Y, results are ordered by population density (largest city first). When a city name is entered (exact or partial), exact matches appear first, followed by keyword-relevance ranking.

Field	Description	France	International
Province	State or administrative region ISO code (e.g. `17` for Japan).	String (50)	String (50)
IDLocalite	Unique city identifier (INSEE code for France).	String (20)	String (20)
Pays	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
Instance	Internal field.	String	String
CodePostal	Postal code of the address.	String (10)	String (10)
SousLocalite	Sub-locality (district, borough, suburb).	Empty	String (50)
LieuDit	Named locality or hamlet (France) or equivalent district-level field (international). Availability varies by country.	String (38)	String (50)
Localite	City name.	String (38)	String (50)
Latitude	Geocoordinates of the matched locality. Not available for all countries - see coverage.	String	String
Longitude	Geocoordinates of the matched locality. Not available for all countries - see coverage.	String	String
IDVoie	Unique street identifier. Populated only when the postal code maps to a specific street. When present, you can skip ADR and pass `IDVoie` directly to COMPL.	String (20)	String (20)
Voie	Street name. Only present in the response when `IDVoie` is populated.	String (38)	String (150)
NbNumero	Total number of house numbers on the matched street. Populated only when `IDVoie` is present; empty otherwise.	String	String
ListeNumero	Semicolon-separated list of valid street numbers for the matched street. Always contains all numbers when present; empty when `IDVoie` is absent.	String (1024)	String (1024)
Numero	Full street number including any complement (bis, ter, etc.).	String (38)	String (38)
TypeVoie	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`). Not returned for all international datasets.	String (20)	String (20)
Complement	Additional address information.	Empty	String (50)
Entreprise	Company name associated with the address.	String (38)	String (38)
Cedex	CEDEX indicator: `1` = CEDEX address, `0` = not CEDEX.	String (1)	String (1)
Region1	State or administrative region ISO label (e.g. `ISHIKAWA` for Japan).	Not available	String (50)
Region2	County or equivalent administrative level.	Not available	String (50)
Region3	County or equivalent (alternate level).	Not available	String (50)
Region4	Additional regional or administrative information.	Not available	String (50)

Response example

Response example - France (75008 Paris)

{
  "1": {
    "Province":     "*",
    "IDLocalite":   "75108",
    "NbNumero":     "",
    "Pays":         "FRA",
    "IDVoie":       "",
    "Cedex":        "0",
    "Numero":       "",
    "TypeVoie":     "",
    "Instance":     "",
    "ListeNumero":  "",
    "CodePostal":   "75008",
    "SousLocalite": "",
    "LieuDit":      "",
    "Latitude":     "48.8775112171854",
    "Localite":     "PARIS",
    "Longitude":    "2.31760169076841",
    "Complement":   "",
    "Entreprise":   ""
  }
}

Response example - Japan (108-6390)

{
  "1": {
    "Cedex":        "0",
    "CodePostal":   "108-6390",
    "Complement":   "",
    "Entreprise":   "",
    "IDLocalite":   "402574_1086390",
    "IDVoie":       "",
    "Instance":     "0",
    "Latitude":     "",
    "LieuDit":      "",
    "ListeNumero":  "",
    "Localite":     "ﾐﾅﾄｸ",
    "Longitude":    "",
    "NbNumero":     "",
    "Numero":       "",
    "Pays":         "JPN",
    "Province":     "13",
    "SousLocalite": "",
    "TypeVoie":     "",
    "Region1":      "ﾄｳｷｮｳﾄ"
  }
}

Errors

HTTP	Error type	Response body
200	Missing or empty `Licence`	`{}` - empty result, no error raised
401	Incorrect or expired `Licence`	`unauthorized_client`
400	Missing `CodePostal` parameter	`Bad Request Parameters * not allowed`
400	Parameter name typo (e.g. `codepostal` instead of `CodePostal`)	`Bad Request Parameters * not allowed`
200	Unrecognised `Pays` ISO code (e.g. `AAA`)	`{}` - empty result, no error raised
401	Invalid country format (e.g. `FRAN` instead of `FRA`)	`unauthorized_country`

Test the API

Click the button below to test this endpoint live in your browser.

Open console

Street search (ADR)

Second step of the funnel approach. Given an IDLocalite from CP and a partial street name, returns matching streets. The IDVoie from each result feeds the final step: COMPL.

Jump to Request Parameters Response Example Errors ▶ Test the API

Request

ADR supports both GET and POST.

{SERVER_ADDRESS} and {LICENCE_CODE} are provided by DQE upon account creation. {CITY_ID} is obtained from the IDLocalite field of the CP response when the user selects a city. Contact your DQE account manager to obtain these credentials.

The Adresse value must be URL-encoded - e.g. l'église → l%27%C3%A9glise.

GET POST

GEThttps://{SERVER_ADDRESS}/ADR/?IDLocalite={CITY_ID}&Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL example

France - IDLocalite from previous CP step

curl "https://{SERVER_ADDRESS}/ADR/?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1"

POSThttps://{SERVER_ADDRESS}/ADR/

Send all parameters in the request body using Content-Type: application/x-www-form-urlencoded. The server address remains in the URL.

cURL example

curl -X POST "https://{SERVER_ADDRESS}/ADR/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "IDLocalite=75108" \
  -d "Adresse=bienfaisance" \
  -d "Pays=FRA" \
  -d "Licence={LICENCE_CODE}"

Parameters

Parameter	Value	Description	Mand / Opt
Licence	`{LICENCE_CODE}`	Your DQE licence key or OAuth2 token. Contact support if you do not yet have one.	Mandatory
IDLocalite	`{CITY_ID}`	City identifier returned by CP in the `IDLocalite` field. Scopes the street search to the selected city.	Mandatory
Adresse	`{INPUT}`	Partial street name entered by the user.	Mandatory
Pays	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Taille	`{LENGTH}`	Maximum character length for address fields returned. Applies to Latin-character addresses only. Default: `38`. Recommended minimum: `32`.	Optional
Instance	`{INSTANCE}`	Not echoed back in results for this endpoint - safe to omit.	Optional
Version=1.1	`1.1`	When set to `1.1`, populates the `LieuDit` field for small towns. Without it, small town names appear in the `Localite` field in brackets instead.	Optional
Langue	`{LANGUAGE}`	Filters results by language/script. JPN: `JP` = Kanji · `JK` = Katakana · `EN` = Romanized. HKG: `EN` · `ZH`. THA: `EN` · `TH`. See Language guide.	Optional

Response

On success, the API returns a JSON object. Keys are rank numbers from "1" to "n", each mapping to a dictionary of street fields.

Field	Description	France	International
label	Ready-to-display string for an autocomplete dropdown. Numbers in `[brackets]` indicate the number was not found in the reference data. See Label field - display only for usage notes. Only use `label` to populate the suggestion dropdown - never to store the address. See integration guide →	Not available	String (255)
IDVoie also: CodeVoie	Unique street identifier. Used as input to COMPL.	String (20)	String (20)
Voie	Street name.	String (38)	String (150)
Saisie	Normalised form of the submitted street input. May differ from the original input in casing or formatting.	String (255)	String (255)
TypeVoie	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`). Not returned for all international datasets.	String (20)	String (20)
Numero also: Num	Full street number including any complement (bis, ter, etc.).	String (38)	String (38)
NumSeul	Street number only, without any complement (bis, ter, etc.).	Not available	String (4)
NbNumero also: Nbnumero	When the queried number is not found or missing, returns the total count of valid street numbers for this street. Both keys (`NbNumero` / `Nbnumero`) refer to the same value. Can be an empty string when not applicable.	String	String
ListeNumero	Semicolon-separated list of valid street numbers. Contains all numbers when no number was entered or when the entered number is not found; contains only the matched number otherwise.	String (1024)	String (1024)
valid_num	Street number validity indicator. `1` if the number exists in the reference data, `0` otherwise. Returns an empty string for some international addresses where number-level validation is not available.	Not available	Integer
CodePostal	Postal code of the address.	String (10)	String (10)
Localite	City name.	String (38)	String (50)
IDLocalite	Unique city identifier (INSEE code for France).	String (20)	String (20)
SousLocalite	Sub-locality (district, borough, suburb).	Not available	String (50)
LieuDit	Named locality. Populated when `Version=1.1` is set in the request. May be populated for international addresses.	String (38)	String (50)
Province	State or administrative region ISO code (e.g. `17` for Japan).	Not available	String (50)
Region1	State or administrative region ISO label (e.g. `ISHIKAWA` for Japan).	Not available	String (50)
Region2	County or equivalent administrative level.	Not available	String (50)
Region3	County or equivalent (alternate level).	Not available	String (50)
Region4	Additional regional or administrative information.	Not available	String (50)
Suburb	Suburb or district.	Not available	String (50)
Thoroughfare	Dependent street.	Not available	UK only
Complement	Additional address information (building name, floor, etc.). Availability varies by country - see integration guide.	Empty	String (50)
Complement2	Second sub-building line. Populated for certain international addresses when both a building identifier and a sub-building identifier (floor, apartment, suite) are available as separate entries, and for certain organisational CEDEX addresses.	Not available	String (50)
Entreprise	Company name associated with the address.	String (38)	String (38)
Cedex	CEDEX indicator: `1` = CEDEX address, `0` = not CEDEX.	String (1)	String (1)
Latitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	String	String
Longitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	String	String
Roudis	Roudis code.	String	Not available
Pays	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
Instance	Internal field.	String	String

Returned with Version=1.1

Street selected without a number? See integration guide →

Response example

Response example - France (Rue de la Bienfaisance, 75008 Paris)

{
  "1": {
    "IDLocalite":  "75108",
    "Saisie":      "bienfaisance",
    "Pays":        "FRA",
    "IDVoie":      "1454259",
    "Voie":        "RUE DE LA BIENFAISANCE",
    "Roudis":      "",
    "ListeNumero": "1;2;3;3B;4;6;7;7B;8;9;10;12;12B;15;16;17;19;20;21;23;25;26;27;28;29;30;32;33;34;35;36;37;39;40;41;42;43;44;45;46;47;48;50;51;52;52B;54",
    "Numero":      "",
    "TypeVoie":    "RUE",
    "Instance":    "",
    "Cedex":       "0",
    "Num":         "",
    "CodePostal":  "75008",
    "NbNumero":    "47",
    "Longitude":   "2.316451",
    "LieuDit":     "",
    "Latitude":    "48.876526",
    "Localite":    "PARIS",
    "CodeVoie":    "1454259",
    "Complement":  "",
    "Entreprise":  ""
  }
}

Response example - Japan (三田, 108-6390)

{
  "1": {
    "label":       "〒108-6390 東京都港区三田",
    "valid_num":   1,
    "Num":         "",
    "Numero":      "",
    "ListeNumero": "",
    "Nbnumero":    0,
    "NbNumero":    0,
    "NumSeul":     "",
    "Saisie":      "三田",
    "Pays":        "JPN",
    "Complement":  "",
    "Voie":        "三田",
    "CodeVoie":    "558203",
    "IDVoie":      "558203",
    "IDLocalite":  "402573",
    "Instance":    1,
    "CodePostal":  "108-6390",
    "Localite":    "港区",
    "Province":    "13",
    "LieuDit":     "",
    "Longitude":   "",
    "Latitude":    "",
    "Region1":     "東京都",
    "Region2":     "港区",
    "Region3":     "",
    "Suburb":      "",
    "TypeVoie":    ""
  }
}

Errors

HTTP	Error type	Response body
200	Missing or empty `Licence`	`{}` - empty result, no error raised
401	Incorrect or expired `Licence`	`unauthorized_client`
400	Missing `IDLocalite`	`Bad Request Parameters * not allowed`
400	Missing `Adresse`	`Bad Request Parameters * not allowed`
400	Missing `Pays`	`Bad Request Parameters * not allowed`
400	Parameter name typo (e.g. misspelling of `Adresse` or `IDLocalite`)	`Bad Request Parameters * not allowed`

Test the API

Click the button below to test this endpoint live in your browser.

Open console

Building (COMPL)

Final step of the funnel approach. Given an IDVoie and Numero from ADR, returns a list of sub-building suggestions: building names, floor numbers, company names, apartment numbers.

Jump to Request Parameters Response Example Errors ▶ Test the API

Request

COMPL supports both GET and POST.

{SERVER_ADDRESS} and {LICENCE_CODE} are provided by DQE upon account creation. {STREET_ID} is obtained from the IDVoie field of the ADR response when the user selects a street. Contact your DQE account manager to obtain these credentials.

GET POST

GEThttps://{SERVER_ADDRESS}/COMPL/?IDVoie={STREET_ID}&IDNum={NUM}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL example

France - IDVoie from previous ADR step

curl "https://{SERVER_ADDRESS}/COMPL/?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}"

When the user has not entered a street number, pass an empty IDNum parameter: &IDNum=

POSThttps://{SERVER_ADDRESS}/COMPL/

Send all parameters in the request body using Content-Type: application/x-www-form-urlencoded. The server address remains in the URL.

cURL example

curl -X POST "https://{SERVER_ADDRESS}/COMPL/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "IDVoie=2408474" \
  -d "IDNum=1" \
  -d "Pays=FRA" \
  -d "Licence={LICENCE_CODE}"

Parameters

Parameter	Value	Description	Mand / Opt
Licence	`{LICENCE_CODE}`	Your DQE licence key or OAuth2 token. Contact support if you do not yet have one.	Mandatory
IDVoie	`{STREETID}`	Unique street identifier returned by ADR in the `IDVoie` field.	Mandatory
IDNum	`{STREETNUMBER}`	Street number selected by the user - corresponds to the `Numero` field from the ADR response.	Mandatory
Pays	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Taille	`{LENGTH}`	Maximum character length for address fields returned. Applies to Latin-character addresses only. Setting this too low may truncate results. Default: `38`. Recommended minimum: `32`.	Optional
Instance	`{INSTANCE}`	Not echoed back in results for this endpoint - safe to omit.	Optional

Response

The JSON response is a dictionary whose keys are numbered from "1" to "n". Each entry contains one address complement.

No sub-building data is not an error. See integration guide →

Field	Description	France	International
Batiment	Building or apartment complement label.	String (38)	String (150)
CodePostal	Postal code associated with the complement.	Not available	String (10)

Response example

Response example - France (1 Rue de la Louisiane, 31200 Toulouse)

{
  "1": {
    "Batiment":   "BATIMENT D RESIDENCE ALLEE DES CEDRES"
  },
  "2": {
    "Batiment":   "BATIMENT A RESIDENCE ALLEE DES CEDRES"
  },
  "3": {
    "Batiment":   "BATIMENT B RESIDENCE ALLEE DES CEDRES"
  },
  "4": {
    "Batiment":   "BATIMENT C RESIDENCE ALLEE DES CEDRES"
  }
}

Response example - International (GBR)

{
  "1": {
    "Batiment":   "Town Hall, Tameside Metropolitan Borough Council",
    "CodePostal": "M34 2AP"
  },
  "2": {
    "Batiment":   "Victoria Park Community Association",
    "CodePostal": "M34 2AP"
  }
}

Errors

HTTP	Error type	Response body
401	Missing or empty `Licence` parameter	`unauthorized_client`
401	Incorrect or expired licence key	`unauthorized_client`
400	Missing `IDVoie` parameter	`Bad Request Parameters empty fields`
400	Missing `IDNum` parameter	`Bad Request Parameters empty fields`
400	Missing `Pays` parameter	`Bad Request Parameters empty fields`
400	Parameter name typo (e.g. `IdVoie` instead of `IDVoie`)	`Bad Request Parameters empty fields`

Test the API

Click the button below to test this endpoint live in your browser.

Open console

Address API - Autocomplete from a postcode (Classic)

City search (CP)

Request

cURL example

cURL example

Parameters

Response

Response example

Errors

Test the API

Street search (ADR)

Request

cURL example

cURL example

Parameters

Response

Response example

Errors

Test the API

Building (COMPL)

Request

cURL example

cURL example

Parameters

Response

Response example

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article