Address API - Autocomplete from a single line (Classic)

Autocomplete - Single line - Standard API

Two-step address autocomplete using the classic API. SINGLEV2 returns ranked address suggestions from free-text input; COMPLV2 retrieves sub-building options after the user selects a suggestion.

Two-step autocomplete flow

The user types freely; SINGLEV2 returns ranked suggestions in real time. After selection, COMPLV2 retrieves sub-building options (building names, floor numbers, apartment numbers).

Step 1/SINGLEV2/Free-text autocomplete → Step 2/COMPLV2/Building & apartment details

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

SINGLEV2

Jump to Request Parameters Response Example Errors ▶ Test the API

Standard API endpoint for address autocomplete. Accepts partial or complete free-text input and returns a ranked list of address suggestions. Each suggestion carries an IDVoie used as input to COMPLV2 for sub-building completion.

When to use SINGLEV2 Use this endpoint to suggest addresses as the user types. It handles partial input (street fragment, postal code, city name) and returns all structured fields ready to populate a form. For verifying that an already-complete address is valid and deliverable, use RNVP instead. See integration guide →

Request

Both GET and POST are supported.

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

Address input must be URL-encoded - e.g. l'église → l%27%C3%A9glise.

GET POST

GEThttps://{SERVER_ADDRESS}/SINGLEV2/?Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL examples

France - partial input

curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=8%20rue%20Victor%20Hugo%20Levall&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&NbMax=20&Version=1"

Japan - Kanji, with Langue parameter

curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=108-6390&Pays=JPN&Taille=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/SINGLEV2/

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

cURL example

France - partial input

curl -X POST "https://{SERVER_ADDRESS}/SINGLEV2/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Adresse=8+rue+Victor+Hugo+Levall" \
  -d "Pays=FRA" \
  -d "Licence={LICENCE_CODE}" \
  -d "Taille=38" \
  -d "NbMax=20" \
  -d "Version=1"

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
Adresse	`{INPUT}`	Free-text address string entered by the user. Accepts partial input - street fragment, street number, postal code, or city name. Must be URL-encoded. No pipe format required - pass the raw string as typed.	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 suggestions returned. Applies to Latin-character addresses only. Setting this too low may truncate results. Default: `38`. Recommended minimum: `32`.	Optional
NbMax	`{NB}`	Maximum number of address suggestions returned. Default: `20`.	Optional
Version	`1`	When set to `1`, the street type is extracted from the `Voie` key and returned in a dedicated `TypeVoie` field. Without this parameter, the street type remains part of `Voie` (e.g., RUE DE LA PAIX) and `TypeVoie` is empty.	Optional
Instance	`{INSTANCE}`	Not echoed back in results for this endpoint - safe to omit.	Optional
Langue	`{LANGUAGE}`	Filters results by language/script (e.g. JPN: `JP` = Kanji · `JK` = Katakana · `EN` = Romanized). See Language guide.	Optional
Filter	`{FILTER}`	France only. Filters CEDEX addresses: `1` all addresses; `2` non-CEDEX only; `3` CEDEX only.	Optional

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. The first result is the closest match to the input.

Business reading: Think of the response as a ranked list of address suggestions. "1" is the best match; higher numbers are alternate candidates. The label field contains the ready-to-display string for your autocomplete dropdown - everything else gives you the structured components to populate form fields.

Key	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 →	String (255)	String (255)
Voie	Street name.	String (38)	String (150)
TypeVoie	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`). Only populated when `Version=1` is set - in that case the street type is removed from `Voie` and returned here instead.	String (20)	String (20)
Numero	Full street number including any complement (bis, ter, etc.).	String (38)	String (38)
Num	Alias for `Numero`. Kept for compatibility - prefer `Numero`.	String (38)	String (38)
NumSeul	Street number only, without any complement (bis, ter, etc.).	String (4)	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. Can be an empty string for some international addresses where this data is not available.	String	String
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.	Integer	Integer
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)
IDVoie also: CodeVoie	Unique street identifier. Used as input to COMPLV2. CodeVoie is kept for compatibility. Prefer IDVoie in new integrations.	String (20)	String (20)
CodePostal	Postal code of the address.	String (10)	String (10)
Localite	City name.	String (38)	String (50)
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)
IDLocalite	Unique city identifier (INSEE code for France).	String (20)	String (20)
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)
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)
Thoroughfare	Dependent street.	Not available	UK only
Pays	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
Latitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	Not available	String
Longitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	Not available	String
Saisie	Normalised form of the submitted address. May differ from the original input in casing or formatting. Not populated for all countries.	String (255)	String (255)
Instance	Internal field.	Empty	String

Populated with Version=1

Street selected without a number? See integration guide →

Response example

United Kingdom - input "Abbey Road NW10 7TJ London"

{
  "1": {
    "label":        "Abbey Road (West London Waste)|NW10 7TJ LONDON",
    "valid_num":    1,
    "Num":          "",
    "Numero":       "",
    "ListeNumero":  "",
    "Nbnumero":     0,
    "NbNumero":     0,
    "NumSeul":      "",
    "Saisie":       "ABBEY ROAD NW10 7TJ LONDON",
    "Pays":         "GBR",
    "Complement":   "",
    "Voie":         "Abbey Road",
    "CodeVoie":     "7831549_NW107TJ",
    "IDVoie":       "7831549_NW107TJ",
    "IDLocalite":   "1745994",
    "Instance":     1,
    "CodePostal":   "NW10 7TJ",
    "Localite":     "LONDON",
    "Province":     "",
    "LieuDit":      "",
    "Longitude":    "",
    "Latitude":     "",
    "Suburb":       "",
    "TypeVoie":     "",
    "Entreprise":   "West London Waste",
    "Thoroughfare": ""
  }
}

Japan - input "三田", Langue=JP

{
  "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":     ""
  },
  "2": {
    "label":        "〒942-0054 新潟県上越市三田",
    "valid_num":    1,
    "Num":          "",
    "Numero":       "",
    "ListeNumero":  "",
    "Nbnumero":     0,
    "NbNumero":     0,
    "NumSeul":      "",
    "Saisie":       "三田",
    "Pays":         "JPN",
    "Complement":   "",
    "Voie":         "三田",
    "CodeVoie":     "537719",
    "IDVoie":       "537719",
    "IDLocalite":   "387092",
    "Instance":     1,
    "CodePostal":   "942-0054",
    "Localite":     "上越市",
    "Province":     "15",
    "LieuDit":      "",
    "Longitude":    "",
    "Latitude":     "",
    "Region1":      "新潟県",
    "Region2":      "上越市",
    "Region3":      "",
    "Suburb":       "",
    "TypeVoie":     ""
  }
  // ... 18 more results
}

Errors

HTTP	Error type	Response body
400	Missing or empty `Licence`	`Bad Request Parameters empty fields`
401	Invalid or unauthorized licence key	`unauthorized_client`
400	Missing or empty `Adresse`	`Bad Request Parameters empty fields`
400	Missing or empty `Pays`	`Bad Request Parameters empty fields`
400	Unrecognized parameter name (e.g. typo in `Adresse`)	`Bad Request Parameters empty fields`

Test the API

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

Open console

COMPLV2

Jump to Request Parameters Response Example Errors ▶ Test the API

Second step of the single-line approach. Given a street ID and street number selected from a SINGLEV2 result, returns a list of sub-building suggestions: building names, floor numbers, company names, apartment numbers.

When to use COMPLV2 Use COMPLV2 after the user has selected a street from SINGLEV2. Pass the IDVoie and IDNum returned by SINGLEV2 to get granular sub-building options. If no sub-building options exist for the address, no numbered entries are returned.

Request

Both GET and POST are supported.

{SERVER_ADDRESS} and {LICENCE_CODE} are provided by DQE upon account creation. {STREET_ID} is obtained from the SINGLEV2 response. Contact your DQE account manager to obtain these credentials.

GET POST

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

cURL example

France

curl "https://{SERVER_ADDRESS}/COMPLV2/?IDVoie=1454602&IDNum=20&Pays=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/COMPLV2/

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

cURL example

France

curl -X POST "https://{SERVER_ADDRESS}/COMPLV2/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "IDVoie=1454602" \
  -d "IDNum=20" \
  -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 SINGLEV2 in the `IDVoie` or `CodeVoie` field.	Mandatory
IDNum	`{STREETNUMBER}`	Street number selected by the user - corresponds to the `Numero` field from the SINGLEV2 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
Filter	`{FILTER}`	For the United States: filters complement suggestions based on what the user has typed. Pass the partial complement type entered (e.g., `FL`, `STE`, `RM`) - only complement entries matching that value are returned.	Optional

Response

On success, the API returns a JSON object with two types of keys. Numbered keys ("1" to "n") each represent a sub-building option. Root-level geographic keys (Latitude, Longitude) give the geocoordinates of the matched address. Geocoding coverage varies by country - see Geographic coverage.

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

Key	Description	France	International
Numbered entries ("1" to "n") - one per sub-building option
Batiment	Additional address label (building name, floor, apartment, etc.).	String (38)	String (150)
CodePostal	Postal code specific to this sub-unit, when available (e.g. ZIP+4 for the USA).	Not available	String (10)
Root-level geographic fields
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
Root-level - optional, France only (requires Iris/Ilot subscription)
Status_IrisIlot	Source of the IRIS/Ilot codes (e.g. `INSEE`).	String (5)	Not available
ilot	Îlot code.	String (9)	Not available
iris	IRIS code.	String (9)	Not available

Response example

France

{
  "1": { "Batiment": "BATIMENT A" },
  "2": { "Batiment": "BATIMENT B" },
  "3": { "Batiment": "BATIMENT C" },
  "4": { "Batiment": "BATIMENT D" },
  "5": { "Batiment": "BATIMENT E" },
  "Latitude":  "48.879024",
  "Longitude": "2.333291"
}

Errors

HTTP	Error type	Response body
400	Missing or empty `Licence`	`Bad Request Parameters empty fields`
500	Invalid or unauthorized licence key	`{}` (empty JSON object)
400	Missing `IDVoie`	`400 Bad Request`
400	Missing `Pays`	`400 Bad Request`
400	Parameter name typo (unrecognized key)	`400 Bad Request`

Test the API

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

Open console

Address API - Autocomplete from a single line (Classic)

SINGLEV2

Request

cURL examples

cURL example

Parameters

Response

Response example

Errors

Test the API

COMPLV2

Request

cURL example

cURL example

Parameters

Response

Response example

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article