Autocomplete - Single line - RESTful
The RESTful single-line autocomplete flow lets users type a free-text address into one field and receive ranked suggestions via the single endpoint, then retrieve sub-building options from compl once they pick a result.
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).
Output casing - The casing follows the
postal norm of the country concerned.
single
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.
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}"
fetch("https://{SERVER_ADDRESS}/v1/single/?"
+ new URLSearchParams({
Address: "8 rue Victor Hugo Levall",
Country: "FRA",
Length: "38",
Limit: "20",
Version: "1",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/single/",
params={
"Address": "8 rue Victor Hugo Levall",
"Country": "FRA",
"Length": "38",
"Limit": "20",
"Version": "1",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'Address' => '8 rue Victor Hugo Levall',
'Country' => 'FRA',
'Length' => '38',
'Limit' => '20',
'Version' => '1',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/single/?{$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/single/',
{
params: {
Address: '8 rue Victor Hugo Levall',
Country: 'FRA',
Length: '38',
Limit: '20',
Version: '1',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/single/"
+ "?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=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/single/"
+
"?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=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/single/"
+
"?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=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))
}
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}"
fetch("https://{SERVER_ADDRESS}/v1/single/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
Address: "8 rue Victor Hugo Levall",
Country: "FRA",
Length: "38",
Limit: "20",
Version: "1",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/single/",
data={
"Address": "8 rue Victor Hugo Levall",
"Country": "FRA",
"Length": "38",
"Limit": "20",
"Version": "1",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/single/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'Address' => '8 rue Victor Hugo Levall',
'Country' => 'FRA',
'Length' => '38',
'Limit' => '20',
'Version' => '1',
'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/single/',
qs.stringify({
Address: '8 rue Victor Hugo Levall',
Country: 'FRA',
Length: '38',
Limit: '20',
Version: '1',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=1&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/single/"))
.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>
{
["Address"] = "8 rue Victor Hugo Levall",
["Country"] = "FRA",
["Length"] = "38",
["Limit"] = "20",
["Version"] = "1",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/single/",
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("Address", "8 rue Victor Hugo Levall")
form.Set("Country", "FRA")
form.Set("Length", "38")
form.Set("Limit", "20")
form.Set("Version", "1")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/single/",
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 |
| 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
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.
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}"
fetch("https://{SERVER_ADDRESS}/v1/compl/?"
+ new URLSearchParams({
StreetId: "1454602",
StreetNumber: "20",
Country: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/compl/",
params={
"StreetId": "1454602",
"StreetNumber": "20",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'StreetId' => '1454602',
'StreetNumber' => '20',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/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}/v1/compl/',
{
params: {
StreetId: '1454602',
StreetNumber: '20',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/compl/"
+ "?StreetId=1454602&StreetNumber=20&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/compl/"
+
"?StreetId=1454602&StreetNumber=20&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/compl/"
+
"?StreetId=1454602&StreetNumber=20&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}/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}"
fetch("https://{SERVER_ADDRESS}/v1/compl/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
StreetId: "1454602",
StreetNumber: "20",
Country: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/compl/",
data={
"StreetId": "1454602",
"StreetNumber": "20",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/compl/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'StreetId' => '1454602',
'StreetNumber' => '20',
'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/compl/',
qs.stringify({
StreetId: '1454602',
StreetNumber: '20',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "StreetId=1454602&StreetNumber=20&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/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>
{
["StreetId"] = "1454602",
["StreetNumber"] = "20",
["Country"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/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("StreetId", "1454602")
form.Set("StreetNumber", "20")
form.Set("Country", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/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 |
| 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
See also
Related to