Use the /funneladdress/ endpoint as the second step in the Restful funnel address search flow. Search for streets within a city using the CityId returned by /funnelpostcode/. Then pass the returned StreetId and StreetNumber to /funnelcompl/ to retrieve address complements.
GET request
Endpoint
https://{SERVER_ADDRESS}/{VERSION}/funneladdress/?CityId={CITY_ID}&Country={COUNTRY_CODE}&Street={INPUT}&Licence={LICENCE_CODE}&Limit={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 |
| CityId | {CITY_ID} | City ID returned by /funnelpostcode/. | Mandatory |
| Country | {COUNTRY_CODE} | ISO 3-letter country code. | Mandatory |
| Street | {INPUT} | User input for the street name. | Mandatory |
| Limit | {INTEGER} | Limits the number of returned responses. | 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}/funneladdress/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 |
| CityId | {CITY_ID} | City ID returned by /funnelpostcode/. | Mandatory |
| Country | {COUNTRY_CODE} | ISO 3-letter country code. | Mandatory |
| Street | {INPUT} | User input for the street name. | Mandatory |
| Limit | {INTEGER} | Limits the number of returned responses. | 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 an Addresses array. Each element contains one street suggestion.
{
"Found": 1,
"Addresses": [
{
"PostalCode": "108-6390",
"City": "ﾐﾅﾄｸ",
"Hamlet": "",
"SpecialDistribution": "",
"Country": "JPN",
"StateCode": "13",
"SubLocality": "",
"CityId": "402574",
"Input": "108-6390",
"Label": "〒108-6390 ﾄｳｷｮｳﾄﾐﾅﾄｸﾐﾀ",
"AdditionalAddress": "",
"StreetNumber": "",
"StreetType": "",
"Street": "ﾐﾀ",
"StreetId": "558204",
"IsValidStreetNumber": 1,
"StreetNumberListCount": 0,
"StreetNumberList": "",
"StreetNumberOnly": "",
"StateLabel": "ﾄｳｷｮｳﾄ",
"AdministrativeArea": "ﾐﾅﾄｸ",
"Suburb": "",
"Company": "",
"Latitude": "",
"Longitude": ""
}
]
}| Field | Meaning | Always in JSON? | Type / Format |
|---|---|---|---|
| PostalCode | Postal / ZIP code. | Yes | STRING(10-20) |
| City | City / ward name. | Yes | STRING(50) |
| Hamlet | Hamlet or dependent locality. | Yes | STRING(50), may be empty |
| SpecialDistribution | Special distribution flag. | Yes | STRING(1), may be empty |
| Country | ISO country code. | Yes | STRING(3) |
| StateCode | State or prefecture code. | Yes | STRING(10) |
| StateLabel | State or prefecture label. | Yes | STRING(50) |
| AdministrativeArea | Administrative area. | Yes | STRING(50) |
| SubLocality | Sub-locality information. | Yes | STRING(50), may be empty |
| Suburb | Suburb or district. | Yes | STRING(255), may be empty |
| CityId | Unique city identifier. | Yes | STRING(20) |
| Input | User input value. | Yes | STRING(50) |
| Label | Formatted display label. | Yes | STRING(255) |
| Street | Street name. | Yes | STRING(255), may be empty |
| StreetId | Street identifier. | Yes | STRING(20), may be empty |
| StreetType | Street type. | Yes | STRING(50), may be empty |
| StreetNumber | Street or house number. | Yes | STRING(20), may be empty |
| StreetNumberOnly | Numeric part of the street number. | Yes | STRING(20), may be empty |
| StreetNumberList | List of valid street numbers. | Yes | STRING(1024), may be empty |
| StreetNumberListCount | Number of items in StreetNumberList. | Yes | INTEGER |
| IsValidStreetNumber | Indicates whether the street number is valid. | Yes | INTEGER |
| AdditionalAddress | Additional address line. | Yes | STRING(255), may be empty |
| Company | Company name. | Yes | STRING(255), may be empty |
| Latitude | Latitude coordinate. | Yes | DECIMAL(18), empty string possible |
| Longitude | Longitude coordinate. | Yes | DECIMAL(18), empty string possible |
Error response
Errors are returned as JSON in the following format:
{
"status": 400,
"message": "Bad Request",
"details": "Missing mandatory parameter: CityId",
"error": "Bad Request"
}| Status | Cause |
|---|---|
400 | Missing mandatory parameter, or invalid parameter value. |
401 | Missing, empty, or incorrect Licence parameter. |