Use the /funnelpostcode/ endpoint as the first step in the Restful funnel address search flow. Search for localities by postal code or city name. Then pass the returned CityId to /funneladdress/ to search streets within the selected city.
GET request
Endpoint
https://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/?PostalCode={POSTAL_CODE}&Country={COUNTRY_CODE}&Extended={EXTENDED}&Licence={LICENCE_CODE}&Limit={INTEGER}&Filter={INTEGER}&Length={LENGTH}&Langue={LANGUAGE}Replace the values in braces with your own information.
| Parameter | Value | Description | Mandatory/Optional |
|---|---|---|---|
| SERVER_ADDRESS | {SERVER_ADDRESS} |
Address of the DQE server that will process the data. | Mandatory |
| VERSION | {VERSION} |
Version of the API (e.g. v1). |
Mandatory |
| Licence | {LICENCE_CODE} |
Licence code assigned to your account or token generated by oauth2. | Mandatory |
| PostalCode | {POSTAL_CODE} |
Postal code or city name input. | Mandatory |
| Country | {COUNTRY_CODE} |
ISO 3-letter country code. | Mandatory |
| Extended |
Y or N
|
France and Belgium only. Enables search with as few as 2 digits entered. | Optional |
| Limit | {INTEGER} |
Limits the number of returned responses. | Optional |
| Filter | {INTEGER} |
Filters returned address types. 1: postal + PO box. 2: postal + street. 3: postal only. 4: one per postal+city (Malaysia only). |
Optional |
| Length | {LENGTH} |
Character limit for the address. | Optional. Recommended minimum: 32. |
| Langue | {LANGUAGE} |
For Japan only: JP Kanji, JK Katakana, EN English. |
Optional |
POST request
Endpoint
https://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/Add the parameters below in the request body using x-www-form-urlencoded.
| Parameter | Value | Description | Mandatory/Optional |
|---|---|---|---|
| Licence | {LICENCE_CODE} |
Licence code assigned to your account or token generated by oauth2. | Mandatory |
| PostalCode | {POSTAL_CODE} |
Postal code or city name input. | Mandatory |
| Country | {COUNTRY_CODE} |
ISO 3-letter country code. | Mandatory |
| Extended |
Y or N
|
France and Belgium only. Enables search with as few as 2 digits. | Optional |
| Limit | {INTEGER} |
Limits the number of returned responses. | Optional |
| Filter | {INTEGER} |
1: postal + PO box. 2: postal + street. 3: postal only. 4: one per postal+city (Malaysia). |
Optional |
| Length | {LENGTH} |
Character limit for the address. | Optional. Recommended minimum: 32. |
| Langue | {LANGUAGE} |
For Japan only: JP Kanji, JK Katakana, EN English. |
Optional |
Response
Success response
The JSON response contains a Found count and a PostalCodes array. Each element contains one locality suggestion.
{
"Found": 2,
"PostalCodes": [
{
"PostalCode": "75008",
"City": "Paris 8e Arrondissement",
"Hamlet": "",
"SpecialDistribution": "",
"Country": "FRA",
"AdministrativeArea": "Ile-de-France",
"StateLabel": "Paris",
"StateCode": "75",
"SubLocality": "",
"CityId": "75056",
"Latitude": "48.875480",
"Longitude": "2.308340",
"Informations": {
"AdditionalAddress": "",
"AdditionalAddress_2": "",
"StreetNumberList": "",
"StreetType": "",
"Street": "",
"Suburb": "",
"StreetId": "",
"Company": ""
}
}
]
}| Key | Description |
|---|---|
| Found | Number of localities returned. |
| PostalCode | Postal code. |
| City | City name. |
| CityId | Unique identifier for the city. Pass this to /funneladdress/. |
| Latitude | Latitude of the city. |
| Longitude | Longitude of the city. |
Error response
| Status | Cause |
|---|---|
400 |
Missing mandatory parameter (PostalCode or Country), or invalid country code. |
401 |
Missing, empty, or incorrect Licence parameter. |