Address API - Autocomplete from a single line (RESTful)

Autocomplete - Single line - RESTful

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

Two-step autocomplete flow

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

Step 1/single/Free-text autocomplete → Step 2/compl/Building & apartment details

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

single

Jump to Request Parameters Response Example Errors ▶ Test the API

RESTful endpoint for address autocomplete. Accepts partial or complete free-text input and returns a ranked list of address suggestions. Each suggestion carries a StreetId used as input to compl for sub-building completion.

When to use single 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 CheckAddress instead. See integration guide →

Request

Both GET and POST are supported.

{SERVER_ADDRESS}, {VERSION} 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}/{VERSION}/single/?Address={INPUT}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL examples

France - partial input

curl "https://{SERVER_ADDRESS}/v1/single/?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=1&Licence={LICENCE_CODE}"

Japan - Kanji, with Langue parameter

curl "https://{SERVER_ADDRESS}/v1/single/?Address=108-6390&Country=JPN&Length=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/single/

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}/v1/single/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Address=8+rue+Victor+Hugo+Levall" \
  -d "Country=FRA" \
  -d "Length=38" \
  -d "Limit=20" \
  -d "Version=1" \
  -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
Address	`{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
Country	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Length	`{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
Limit	`{NB}`	Maximum number of address suggestions returned. Default: `20`.	Optional
Version	`1`	When set to `1`, the street type is extracted from the `Street` key and returned in a dedicated `StreetType` field. Without this parameter, the street type remains part of `Street` (e.g., RUE DE LA PAIX) and `StreetType` is empty.	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 response is a JSON object with two top-level keys: Found (integer) and Addresses (array of address suggestion objects, up to Limit items). The first result is the closest match to the input.

Business reading: Think of the response as a ranked list of address suggestions. Addresses[0] is the best match; items further down the array 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.

Top-level

Key	Description	Type
Found	Number of address suggestion objects returned.	Integer
Addresses	Array of address suggestion objects.	Array

Address suggestion object - `Addresses[n]`

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)
Street	Street name.	String (38)	String (150)
StreetType	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`). Only populated when `Version=1` is set - in that case the street type is removed from `Street` and returned here instead.	String (20)	String (20)
StreetNumber	Full street number including any complement (bis, ter, etc.).	String (38)	String (38)
StreetNumberOnly	Street number only, without any complement (bis, ter, etc.).	String (4)	String (4)
StreetNumberListCount	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
IsValidStreetNumber	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
StreetNumberList	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)
StreetId	Unique street identifier. Used as input to compl.	String (20)	String (20)
PostalCode	Postal code of the address.	String (10)	String (10)
City	City name.	String (38)	String (50)
Hamlet	Named locality or hamlet (France) or equivalent district-level field (international). Availability varies by country.	String (38)	String (50)
SubLocality	Sub-locality (district, borough, suburb).	Empty	String (50)
SpecialDistribution	Not in use. Always returned as an empty string.	String	String
CityId	Unique city identifier (INSEE code for France).	String (20)	String (20)
StateCode	State or administrative region ISO code (e.g. `17` for Japan).	Empty	String (50)
StateLabel	State or administrative region ISO label (e.g. `ISHIKAWA` for Japan).	Not available	String (50)
AdministrativeArea	County or equivalent administrative level.	Empty	String (50)
Suburb	Suburb or district.	Empty	String (50)
AdditionalAddress	Additional address information (building name, floor, etc.). Availability varies by country - see integration guide.	Empty	String (50)
Company	Company name associated with the address.	String (38)	String (38)
Input	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)
Country	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
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

Populated with Version=1

Street selected without a number? See integration guide →

Response example

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

{
  "Found": 1,
  "Addresses": [
    {
      "PostalCode":           "NW10 7TJ",
      "City":                 "LONDON",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "GBR",
      "StateCode":            "",
      "SubLocality":          "",
      "CityId":               "1745994",
      "Input":                "ABBEY ROAD NW10 7TJ LONDON",
      "Label":                "Abbey Road (West London Waste)|NW10 7TJ LONDON",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "Abbey Road",
      "StreetId":             "7831549_NW107TJ",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "",
      "AdministrativeArea":   "",
      "Suburb":               "",
      "Company":              "West London Waste",
      "Latitude":             "",
      "Longitude":            "" }
  ]
}

Japan - input "三田", Langue=JP

{
  "Found": 20,
  "Addresses": [
    {
      "PostalCode":           "108-6390",
      "City":                 "港区",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "13",
      "SubLocality":          "",
      "CityId":               "402573",
      "Input":                "三田",
      "Label":                "〒108-6390 東京都港区三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "558203",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "東京都",
      "AdministrativeArea":   "港区",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" },
    {
      "PostalCode":           "942-0054",
      "City":                 "上越市",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "15",
      "SubLocality":          "",
      "CityId":               "387092",
      "Input":                "三田",
      "Label":                "〒942-0054 新潟県上越市三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "537719",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "新潟県",
      "AdministrativeArea":   "上越市",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" }
    // ... 18 more results
  ]
}

Errors

The RESTful endpoint returns a structured JSON error body with an HTTP status code, a message, and an error identifier.

HTTP	Error type	Response body
400	Missing `Licence` parameter	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
400	Empty `Licence` parameter	{"status":400,"message":"Licence must be filled","details":"Empty","error":"bad request"}
401	Incorrect licence number	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{WRONG}","error":"unauthorized_client"}
400	Missing `Address` parameter	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}
400	Missing `Country` parameter	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	Empty `Country` parameter	{"status":400,"message":"Country must be filled","details":"Empty","error":"bad request"}
400	Typo in parameter name	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}

Test the API

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

Open console

compl

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 single result, returns a list of sub-building suggestions: building names, floor numbers, company names, apartment numbers.

When to use compl Use compl after the user has selected a street from single. Pass the StreetId and StreetNumber returned by single 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}, {VERSION} and {LICENCE_CODE} are provided by DQE upon account creation. {STREETID} is obtained from the single response. Contact your DQE account manager to obtain these credentials.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/compl/?StreetId={STREETID}&StreetNumber={STREETNUMBER}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL example

France

curl "https://{SERVER_ADDRESS}/v1/compl/?StreetId=1454602&StreetNumber=20&Country=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/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

France

curl -X POST "https://{SERVER_ADDRESS}/v1/compl/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "StreetId=1454602" \
  -d "StreetNumber=20" \
  -d "Country=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
StreetId	`{STREETID}`	Unique street identifier returned by single in the `StreetId` field.	Mandatory
StreetNumber	`{STREETNUMBER}`	Street number selected by the user - corresponds to the `StreetNumber` field from the single response.	Mandatory
Country	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Length	`{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
Search	`{SEARCH}`	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 response is a JSON object with two top-level keys: Found and AdditionalAddresses (array), plus a Geolocalisation object. Geocoding coverage varies by country - see Geographic coverage.

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

Key	Description	France	International
Found	Number of address complements found.	Integer	Integer
AdditionalAddresses	Array of additional address objects.	Array	Array
AdditionalAddresses[0]. AdditionalAddress	Additional address label (building name, floor, apartment, etc.).	String (38)	String (150)
AdditionalAddresses[0]. PostalCode	Postal code specific to this sub-unit, when available (e.g. ZIP+4 for the USA).	Empty	String (10)
Geolocalisation	Geolocation information for the address.	Object	Object
Geolocalisation. Latitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	String	String
Geolocalisation. Longitude	Geocoordinates of the matched address. Not available for all countries - see coverage.	String	String

Response example

France

{
  "Found": 5,
  "AdditionalAddresses": [
    { "AdditionalAddress": "BATIMENT A", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT B", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT C", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT D", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT E", "PostalCode": "" }
  ],
  "Geolocalisation": {
    "Latitude":  "48.879024",
    "Longitude": "2.333291" }
}

Errors

HTTP	Error type	Response body
400	Missing `StreetId`	{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad request"}
400	Missing `StreetNumber`	{"status":400,"message":"Missing parameters","details":"StreetNumber","error":"bad request"}
400	Missing `Country`	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	Missing `Licence`	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
401	Unauthorized client (licence invalid, expired, or out of scope)	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{INVALID_LICENCE}","error":"unauthorized_client"}

Test the API

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

Open console

Address API - Autocomplete from a single line (RESTful)

single

Request

cURL examples

cURL example

Parameters

Response

Top-level

Address suggestion object - `Addresses[n]`

Response example

Errors

Test the API

compl

Request

cURL example

cURL example

Parameters

Response

Response example

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article

single

Request

cURL examples

cURL example

Parameters

Response

Top-level

Address suggestion object - Addresses[n]

Response example

Errors

Test the API

compl

Request

cURL example

cURL example

Parameters

Response

Response example

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article

Address suggestion object - `Addresses[n]`