Funnel autocomplete - Standard API
Build a postcode-first address form with the classic CP/ADR/COMPL endpoints: look up the city from a postal code or name, list its streets, then surface sub-building options once a street is chosen.
Three-step autocomplete flow
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.
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.
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}"
fetch("https://{SERVER_ADDRESS}/CP/?" + new
URLSearchParams({
CodePostal: "75008",
Alpha: "True",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/CP/",
params={
"CodePostal": "75008",
"Alpha": "True",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'CodePostal' => '75008',
'Alpha' => 'True',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/CP/?{$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}/CP/',
{
params: {
CodePostal: '75008',
Alpha: 'True',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/CP/"
+ "?CodePostal=75008&Alpha=True&Pays=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}/CP/"
+
"?CodePostal=75008&Alpha=True&Pays=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}/CP/" +
"?CodePostal=75008&Alpha=True&Pays=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}/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}"
fetch("https://{SERVER_ADDRESS}/CP/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
CodePostal: "75008",
Alpha: "True",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/CP/",
data={
"CodePostal": "75008",
"Alpha": "True",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/CP/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'CodePostal' => '75008',
'Alpha' => 'True',
'Pays' => '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}/CP/',
qs.stringify({
CodePostal: '75008',
Alpha: 'True',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/CP/"))
.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>
{
["CodePostal"] = "75008",
["Alpha"] = "True",
["Pays"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/CP/",
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("CodePostal", "75008")
form.Set("Alpha", "True")
form.Set("Pays", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/CP/",
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 |
| 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 also: Nbnumero |
Total number of house numbers on the matched
street. Populated only when IDVoie
is present; empty otherwise. Both keys
(NbNumero / Nbnumero)
refer to the same value.
|
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.
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.
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"
fetch("https://{SERVER_ADDRESS}/ADR/?" +
new URLSearchParams({
IDLocalite: "75108",
Adresse: "bienfaisance",
Pays: "FRA",
Licence: "{LICENCE_CODE}",
Taille: "38",
Version: "1.1"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/ADR/",
params={
"IDLocalite": "75108",
"Adresse": "bienfaisance",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
"Taille": "38",
"Version": "1.1",
},
)
print(response.json())
<?php
$params = http_build_query([
'IDLocalite' => '75108',
'Adresse' => 'bienfaisance',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
'Taille' => '38',
'Version' => '1.1',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/ADR/?{$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}/ADR/',
{
params: {
IDLocalite: '75108',
Adresse: 'bienfaisance',
Pays: 'FRA',
Licence: '{LICENCE_CODE}',
Taille: '38',
Version: '1.1'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/ADR/"
+ "?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1";
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}/ADR/"
+
"?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1";
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}/ADR/" +
"?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1"
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}/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}"
fetch("https://{SERVER_ADDRESS}/ADR/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
IDLocalite: "75108",
Adresse: "bienfaisance",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/ADR/",
data={
"IDLocalite": "75108",
"Adresse": "bienfaisance",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/ADR/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'IDLocalite' => '75108',
'Adresse' => 'bienfaisance',
'Pays' => '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}/ADR/',
qs.stringify({
IDLocalite: '75108',
Adresse: 'bienfaisance',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/ADR/"))
.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>
{
["IDLocalite"] = "75108",
["Adresse"] = "bienfaisance",
["Pays"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/ADR/",
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("IDLocalite", "75108")
form.Set("Adresse", "bienfaisance")
form.Set("Pays", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/ADR/",
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 |
| 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.
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.
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}"
fetch("https://{SERVER_ADDRESS}/COMPL/?"
+ new URLSearchParams({
IDVoie: "2408474",
IDNum: "1",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/COMPL/",
params={
"IDVoie": "2408474",
"IDNum": "1",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'IDVoie' => '2408474',
'IDNum' => '1',
'Pays' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/COMPL/?{$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}/COMPL/',
{
params: {
IDVoie: '2408474',
IDNum: '1',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/COMPL/"
+ "?IDVoie=2408474&IDNum=1&Pays=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}/COMPL/"
+
"?IDVoie=2408474&IDNum=1&Pays=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}/COMPL/"
+
"?IDVoie=2408474&IDNum=1&Pays=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))
}
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}"
fetch("https://{SERVER_ADDRESS}/COMPL/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
IDVoie: "2408474",
IDNum: "1",
Pays: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/COMPL/",
data={
"IDVoie": "2408474",
"IDNum": "1",
"Pays": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/COMPL/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'IDVoie' => '2408474',
'IDNum' => '1',
'Pays' => '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}/COMPL/',
qs.stringify({
IDVoie: '2408474',
IDNum: '1',
Pays: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/COMPL/"))
.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>
{
["IDVoie"] = "2408474",
["IDNum"] = "1",
["Pays"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/COMPL/",
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("IDVoie", "2408474")
form.Set("IDNum", "1")
form.Set("Pays", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/COMPL/",
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 |
| 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
See also
Related to