Funnel autocomplete - RESTful
The RESTful funnelpostcode / funneladdress / funnelcompl endpoints power a guided, postcode-first autocomplete: narrow down to a city, list its streets, then fetch sub-building details for the chosen address.
Three-step autocomplete flow
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.
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.
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}"
fetch("https://{SERVER_ADDRESS}/v1/funnelpostcode/?"
+ new URLSearchParams({
PostalCode: "75008",
Country: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/funnelpostcode/",
params={
"PostalCode": "75008",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'PostalCode' => '75008',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelpostcode/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/funnelpostcode/',
{
params: {
PostalCode: '75008',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
+ "?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
+
"?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
+
"?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
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}"
fetch("https://{SERVER_ADDRESS}/v1/funnelpostcode/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
PostalCode: "75008",
Country: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/funnelpostcode/",
data={
"PostalCode": "75008",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelpostcode/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'PostalCode' => '75008',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/funnelpostcode/',
qs.stringify({
PostalCode: '75008',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/funnelpostcode/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["PostalCode"] = "75008",
["Country"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/funnelpostcode/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("PostalCode", "75008")
form.Set("Country", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/funnelpostcode/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
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 |
| Length |
{LENGTH}
|
Maximum character length for address fields
returned. Applies to Latin-character addresses
only. Default: 38. Recommended
minimum: 32.
|
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"}
details echoes back the value
you
sent in Country - it will show
your actual input, not always the literal
INVALID shown here.
|
| 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.
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.
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}"
fetch("https://{SERVER_ADDRESS}/v1/funneladdress/?"
+ new URLSearchParams({
CityId: "75108",
Country: "FRA",
Street: "bienfaisance",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/funneladdress/",
params={
"CityId": "75108",
"Country": "FRA",
"Street": "bienfaisance",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'CityId' => '75108',
'Country' => 'FRA',
'Street' => 'bienfaisance',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funneladdress/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/funneladdress/',
{
params: {
CityId: '75108',
Country: 'FRA',
Street: 'bienfaisance',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/funneladdress/"
+ "?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/funneladdress/"
+
"?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/funneladdress/"
+
"?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
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}"
fetch("https://{SERVER_ADDRESS}/v1/funneladdress/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
CityId: "75108",
Country: "FRA",
Street: "bienfaisance",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/funneladdress/",
data={
"CityId": "75108",
"Country": "FRA",
"Street": "bienfaisance",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funneladdress/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'CityId' => '75108',
'Country' => 'FRA',
'Street' => 'bienfaisance',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/funneladdress/',
qs.stringify({
CityId: '75108',
Country: 'FRA',
Street: 'bienfaisance',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/funneladdress/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["CityId"] = "75108",
["Country"] = "FRA",
["Street"] = "bienfaisance",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/funneladdress/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("CityId", "75108")
form.Set("Country", "FRA")
form.Set("Street", "bienfaisance")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/funneladdress/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
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"}
details echoes back the value
you
sent in Country - it will show
your actual input, not always the literal
JPNde shown here.
|
| 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.
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.
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}"
fetch("https://{SERVER_ADDRESS}/v1/funnelcompl/?"
+ new URLSearchParams({
StreetId: "2408474",
Country: "FRA",
StreetNumber: "1",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/funnelcompl/",
params={
"StreetId": "2408474",
"Country": "FRA",
"StreetNumber": "1",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'StreetId' => '2408474',
'Country' => 'FRA',
'StreetNumber' => '1',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelcompl/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/funnelcompl/',
{
params: {
StreetId: '2408474',
Country: 'FRA',
StreetNumber: '1',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/funnelcompl/"
+ "?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/funnelcompl/"
+
"?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/funnelcompl/"
+
"?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
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}"
fetch("https://{SERVER_ADDRESS}/v1/funnelcompl/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
StreetId: "0751080070",
Country: "FRA",
StreetNumber: "17",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/funnelcompl/",
data={
"StreetId": "0751080070",
"Country": "FRA",
"StreetNumber": "17",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelcompl/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'StreetId' => '0751080070',
'Country' => 'FRA',
'StreetNumber' => '17',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/funnelcompl/',
qs.stringify({
StreetId: '0751080070',
Country: 'FRA',
StreetNumber: '17',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "StreetId=0751080070&Country=FRA&StreetNumber=17&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/funnelcompl/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["StreetId"] = "0751080070",
["Country"] = "FRA",
["StreetNumber"] = "17",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/funnelcompl/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("StreetId", "0751080070")
form.Set("Country", "FRA")
form.Set("StreetNumber", "17")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/funnelcompl/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
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"}
details echoes back the value
you
sent in Country - it will show
your actual input, not always the literal
JPNde shown here.
|
| 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
See also
Related to