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": ""
}
},
{
"PostalCode": "75380",
"City": "Paris Cedex 08",
"Hamlet": "",
"SpecialDistribution": "CEDEX",
"Country": "FRA",
"CityId": "75056",
"Latitude": "48.875480",
"Longitude": "2.308340",
"Informations": {}
}
]
}| Key | Description |
|---|---|
| Found | Number of localities returned. |
| PostalCode | Postal code. |
| City | City name. |
| Hamlet | Dependent locality or hamlet. |
| SpecialDistribution | Cedex or special distribution indicator. |
| Country | ISO country code. |
| AdministrativeArea | Administrative area. |
| StateLabel | State or region label. |
| StateCode | State or region code. |
| SubLocality | Sub-locality. |
| CityId | Unique identifier for the city. Pass this to /funneladdress/. |
| Latitude | Latitude of the city. |
| Longitude | Longitude of the city. |
| Informations.AdditionalAddress | Additional address information (populated when postal code refers to a specific address). |
| Informations.AdditionalAddress_2 | Second additional address information. |
| Informations.StreetNumberList | List of available street numbers. |
| Informations.StreetType | Street type. |
| Informations.Street | Street name. |
| Informations.Suburb | Suburb. |
| Informations.StreetId | Street identifier. |
| Informations.Company | Company name. |
Error response
Errors are returned as JSON in the following format:
{
"status": 400,
"message": "Bad Request",
"details": "Missing mandatory parameter: PostalCode",
"error": "Bad Request"
}| Status | Cause |
|---|---|
400 | Missing mandatory parameter (PostalCode or Country), or invalid country code. |
401 | Missing, empty, or incorrect Licence parameter. |