Address API - Autocomplete from a postcode (RESTful)

Funnel autocomplete - RESTful

Three-step address autocomplete using the RESTful API. funnelpostcode finds matching cities from postal code or city name input; funneladdress returns streets within the selected city; funnelcompl retrieves sub-building options after street selection.

Three-step autocomplete flow

Step 1/funnelpostcode/City search → Step 2/funneladdress/Street search → Step 3/funnelcompl/Building & apartment details

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

City selection (funnelpostcode)

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

Jump to Request Parameters Response Example Errors ▶ Test the API

Request

funnelpostcode supports both GET and POST.

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

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/?PostalCode={POSTAL_CODE}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL example

France - Search by postal code

curl "https://{SERVER_ADDRESS}/v1/funnelpostcode/?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/

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}/v1/funnelpostcode/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "PostalCode=75008" \
  -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
PostalCode	`{POSTAL_CODE}`	Postal code or city name input.	Mandatory
Country	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Extended	`Y` or `N`	Enables search from just 2 characters in the postal code input. Default: `N`.	Optional
Limit	`{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). funnelpostcode will return one result row per municipality.

Response

On success, the API returns a JSON object containing a Found count and a PostalCodes array.

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 Extended=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.

Top-level

Key	Description	Type
Found	Number of locality suggestion objects returned.	Integer
PostalCodes	Array of locality suggestion objects.	Array

Locality suggestion object - `PostalCodes[n]`

Key	Description	France	International
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)
SpecialDistribution	CEDEX indicator: `1` = CEDEX address, `0` = not CEDEX.	String (1)	String (1)
Country	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
AdministrativeArea	County or equivalent administrative level.	Empty	String (50)
StateLabel	State or administrative region ISO label (e.g. `ISHIKAWA` for Japan).	Not available	String (50)
StateCode	State or administrative region ISO code (e.g. `17` for Japan).	String (50)	String (50)
SubLocality	Sub-locality (district, borough, suburb).	Empty	String (50)
CityId	Unique city identifier (INSEE code for France).	String (20)	String (20)
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

Informations object - `PostalCodes[n].Informations`

Populated only when the postal code maps directly to a specific address (e.g. CEDEX codes in France). Otherwise all fields are empty.

Key	Description	France	International
AdditionalAddress	Additional address line.	Empty	String (50)
AdditionalAddress_2	Second additional address line.	Empty	String (50)
StreetNumberList	Semicolon-separated list of valid street numbers for the matched street. Always contains all numbers when present; empty when `StreetId` is absent.	String (1024)	String (1024)
StreetType	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`). Not returned for all international datasets.	String (20)	String (20)
Street	Street name.	String (38)	String (150)
Suburb	Suburb or district.	Empty	String (50)
StreetId	Unique street identifier. Populated only when the postal code maps to a specific street. When present, you can skip funneladdress and pass `StreetId` directly to funnelcompl.	String (20)	String (20)
Company	Company name.	String (38)	String (38)

Response example

Response example - France (75008 Paris)

{
  "Found": 1,
  "PostalCodes": [
    {
      "PostalCode":           "75008",
      "City":                 "PARIS",
      "Hamlet":               "",
      "SpecialDistribution":  "0",
      "Country":              "FRA",
      "AdministrativeArea":   "",
      "StateLabel":           "",
      "StateCode":            "*",
      "SubLocality":          "",
      "CityId":               "75108",
      "Latitude":             "48.8775112171854",
      "Longitude":            "2.31760169076841",
      "Informations": {
        "AdditionalAddress":    "",
        "AdditionalAddress_2":  "",
        "StreetNumberList":     "",
        "StreetType":           "",
        "Street":               "",
        "Suburb":               "",
        "StreetId":             "",
        "Company":              ""
      }
    }
  ]
}

Response example - Japan (108-6390)

{
  "Found": 3,
  "PostalCodes": [
    {
      "PostalCode":           "108-6390",
      "City":                 "ﾐﾅﾄｸ",
      "Hamlet":               "",
      "SpecialDistribution":  "0",
      "Country":              "JPN",
      "AdministrativeArea":   "ﾐﾅﾄｸ",
      "StateLabel":           "ﾄｳｷﾖｳﾄ",
      "StateCode":            "13",
      "SubLocality":          "",
      "CityId":               "402574_1086390",
      "Latitude":             "",
      "Longitude":            "",
      "Informations": {
        "AdditionalAddress":    "",
        "AdditionalAddress_2":  "",
        "StreetNumberList":     "",
        "StreetType":           "",
        "Street":               "",
        "Suburb":               "",
        "StreetId":             "",
        "Company":              ""
      }
    }
  ]
}

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 a mandatory parameter	{"status":400,"message":"Missing parameters","details":"PostalCode,Licence","error":"bad request"}
400	Country code is not valid ISO 3166-1 alpha-3	{"status":400,"message":"Country doesn't exist","details":"INVALID","error":"bad request"}
401	Incorrect or unauthorized licence number	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"WRONG","error":"unauthorized_client"}

Test the API

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

Open console

Address search (funneladdress)

Second step of the funnel approach. Given a CityId from funnelpostcode and a partial street name, returns matching streets. The StreetId from each result feeds the final step: funnelcompl.

Jump to Request Parameters Response Example Errors ▶ Test the API

Request

funneladdress supports both GET and POST.

{SERVER_ADDRESS}, {VERSION} and {LICENCE_CODE} are provided by DQE upon account creation. {CITY_ID} is obtained from the funnelpostcode response when the user selects a city. 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}/funneladdress/?CityId={CITY_ID}&Country={COUNTRY_CODE}&Street={INPUT}&Licence={LICENCE_CODE}

cURL example

France - CityId from previous funnelpostcode step

curl "https://{SERVER_ADDRESS}/v1/funneladdress/?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/funneladdress/

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}/v1/funneladdress/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "CityId=75108" \
  -d "Country=FRA" \
  -d "Street=bienfaisance" \
  -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
CityId	`{CITY_ID}`	City identifier returned by funnelpostcode in the `CityId` field. Scopes the street search to the selected city.	Mandatory
Country	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
Street	`{INPUT}`	Partial street name entered by the user.	Mandatory
Limit	`{NB}`	Maximum number of address suggestions returned.	Optional
Length	`{LENGTH}`	Maximum character length for address fields returned. Applies to Latin-character addresses only. Default: `38`. Recommended minimum: `32`.	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
Version	`1.1`	When set to `1.1`, populates the `Hamlet` field for small towns. Without it, small town names appear in the `City` field in brackets instead.	Optional

Response

On success, the response is a JSON object with two top-level keys: Found (integer) and Addresses (array of address suggestion objects).

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
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). Populated when `Version=1.1` is set. Availability varies by country.	String (38)	String (50)
SpecialDistribution	CEDEX indicator: `1` = CEDEX address, `0` = not CEDEX.	String (1)	String (1)
Country	ISO 3166-1 alpha-3 country code.	String (3)	String (3)
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)
SubLocality	Sub-locality (district, borough, suburb).	Empty	String (50)
Suburb	Suburb or district.	Empty	String (50)
CityId	Unique city identifier (INSEE code for France).	String (20)	String (20)
Input	Normalised form of the submitted street input. May differ from the original input in casing or formatting.	String (255)	String (255)
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 →	Empty	String (255)
Street	Street name.	String (38)	String (150)
StreetId	Unique street identifier. Used as input to funnelcompl.	String (20)	String (20)
StreetType	Street type (e.g., `RUE`, `AVENUE`, `BOULEVARD`). Not returned for all international datasets.	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.).	Empty	String (4)
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)
StreetNumberListCount	When the queried number is not found or missing, returns the total count of valid street numbers for this street.	Empty	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.	Not available	Integer
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)
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 when Version=1.1

Street selected without a number? See integration guide →

Response example

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

{
  "Found": 1,
  "Addresses": [
    {
      "PostalCode":           "75008",
      "City":                 "PARIS",
      "Hamlet":               "",
      "SpecialDistribution":  "0",
      "Country":              "FRA",
      "StateCode":            "",
      "SubLocality":          "",
      "CityId":               "75108",
      "Input":                "bienfaisance",
      "Label":                "",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "RUE",
      "Street":               "RUE DE LA BIENFAISANCE",
      "StreetId":             "1454259",
      "IsValidStreetNumber":  "",
      "StreetNumberListCount":"",
      "StreetNumberList":     "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",
      "StreetNumberOnly":     "",
      "StateLabel":           "",
      "AdministrativeArea":   "",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "48.876526",
      "Longitude":            "2.316451" }
  ]
}

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

Japan - CityId 402573_1086390, Langue=JP (Kanji)

{
  "Found": 1,
  "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":            "" }
  ]
}

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 a mandatory parameter	{"status":400,"message":"Missing parameters","details":"CityID","error":"bad request"}
400	Country code is not valid ISO 3166-1 alpha-3	{"status":400,"message":"Country doesn't exist","details":"JPNde","error":"bad request"}
401	Incorrect or unauthorized licence number	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"WRONG LICENSE","error":"unauthorized_client"}

Test the API

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

Open console

Building (funnelcompl)

Final step of the funnel approach. Given a StreetId and StreetNumber from funneladdress, 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

funnelcompl supports both GET and POST.

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

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/funnelcompl/?StreetId={STREET_ID}&Country={COUNTRY_CODE}&StreetNumber={NUMBER}&Licence={LICENCE_CODE}

cURL example

France - StreetId from previous funneladdress step

curl "https://{SERVER_ADDRESS}/v1/funnelcompl/?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}"

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

POSThttps://{SERVER_ADDRESS}/{VERSION}/funnelcompl/

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}/v1/funnelcompl/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "StreetId=0751080070" \
  -d "Country=FRA" \
  -d "StreetNumber=17" \
  -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	`{STREET_ID}`	Unique street identifier returned by funneladdress in the `StreetId` field.	Mandatory
Country	`{COUNTRY_CODE}`	ISO 3166-1 alpha-3 country code for the address search scope. Example: `FRA` or `GBR`.	Mandatory
StreetNumber	`{NUMBER}`	Street number selected by the user - corresponds to the `StreetNumber` field from the funneladdress response.	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

Response

On success, the response is a JSON object with three top-level keys: Found, AdditionalAddresses (array), and a Geolocalisation geocoordinates object.

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

Top-level

Key	Description	Type
Found	Number of address complement objects returned.	Integer
AdditionalAddresses	Array of address complement objects.	Array
Geolocalisation	Geocoordinates of the matched address. Empty when not available for this address type.	Object

AdditionalAddress object - `AdditionalAddresses[n]`

Key	Description	France	International
AdditionalAddress	Building or apartment complement label.	String (38)	String (150)
PostalCode	Postal code associated with the complement.	String	String

Geocoordinates - `Geolocalisation`

Key	Description	France	International
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

Response example

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

{
  "Found": 4,
  "AdditionalAddresses": [
    { "AdditionalAddress": "BATIMENT A RESIDENCE ALLEE DES CEDRES", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT B RESIDENCE ALLEE DES CEDRES", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT C RESIDENCE ALLEE DES CEDRES", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT D RESIDENCE ALLEE DES CEDRES", "PostalCode": "" }
  ],
  "Geolocalisation": {
      "Latitude":  "",
      "Longitude": "" }
}

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 a mandatory parameter	{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad request"}
400	Country code is not valid ISO 3166-1 alpha-3	{"status":400,"message":"Country doesn't exist","details":"JPNde","error":"bad request"}
401	Incorrect or unauthorized licence number	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"WRONG LICENSE","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 postcode (RESTful)

City selection (funnelpostcode)

Request

cURL example

cURL example

Parameters

Response

Top-level

Locality suggestion object - `PostalCodes[n]`

Informations object - `PostalCodes[n].Informations`

Response example

Errors

Test the API

Address search (funneladdress)

Request

cURL example

cURL example

Parameters

Response

Top-level

Address suggestion object - `Addresses[n]`

Response example

Errors

Test the API

Building (funnelcompl)

Request

cURL example

cURL example

Parameters

Response

Top-level

AdditionalAddress object - `AdditionalAddresses[n]`

Geocoordinates - `Geolocalisation`

Response example

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article

City selection (funnelpostcode)

Request

cURL example

cURL example

Parameters

Response

Top-level

Locality suggestion object - PostalCodes[n]

Informations object - PostalCodes[n].Informations

Response example

Errors

Test the API

Address search (funneladdress)

Request

cURL example

cURL example

Parameters

Response

Top-level

Address suggestion object - Addresses[n]

Response example

Errors

Test the API

Building (funnelcompl)

Request

cURL example

cURL example

Parameters

Response

Top-level

AdditionalAddress object - AdditionalAddresses[n]

Geocoordinates - Geolocalisation

Response example

Errors

Test the API

See also

Was this article helpful?

Previous article

Next article

Locality suggestion object - `PostalCodes[n]`

Informations object - `PostalCodes[n].Informations`

Address suggestion object - `Addresses[n]`

AdditionalAddress object - `AdditionalAddresses[n]`

Geocoordinates - `Geolocalisation`