The /lookup endpoint is used in the Lookup search type.
Name | Type | Description |
---|---|---|
Auth-Token | string | Input your unique token here. This is required to submit an API request. |
x-app-key (Optional) |
string | Alternative authentication header. Auth-Token takes precedence. |
Reference-Id (Optional) |
string | Identifier that will be returned to the response to help you track the request. |
Timeout-Seconds (Optional) |
integer | Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned. The default value of this setting is 15. |
Name | Type | Description |
---|---|---|
Auth-Token | string | Input your unique token here. This is required to submit an API request. |
x-app-key (Optional) |
string | Alternative authentication header. Auth-Token takes precedence. |
Reference-Id (Optional) |
string | Identifier that will be returned to the response to help you track the request. |
Timeout-Seconds (Optional) |
integer | Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned. The default value of this setting is 15. |
Add-Addresses (Optional) |
boolean | Specifies if the response should contain a list of matched addresses. The default value of this setting is false. |
In the request body you can specify:
Name | Type | Description | |
---|---|---|---|
country_iso | string | The ISO3 code of the country you want to search against. | |
datasets | collection | The collection of datasets you want to search against (multiple datasets are currently only supported for UK). | |
key | object | ||
type (Optional) |
string | Specify the type of lookup you want to do. The default value of this setting is default. |
|
value | string | Specify the search term for your lookup. |
Name | Type | Description | |
---|---|---|---|
country_iso | string | The ISO3 code of the country you want to search against. | |
datasets | collection | The collection of datasets you want to search against (multiple datasets are currently only supported for UK). | |
max_addresses (Optional) |
integer | The maximum number of addresses you want to get returned. Acceptable values: 1-1000 This parameter is only relevant if the Add-Addresses header is set.The default value of this setting is 7. |
|
key | object | ||
type | string | Specify the type of lookup you want to do. The available values are:
|
|
value | string | Specify the search term for your lookup. |
The response from the API returns the below fields within a result
object. Should an error occur, an error
object is returned instead.
Name | Type | Description | |
---|---|---|---|
more_results_available | boolean | To indicate that there are more suggestions available than returned in this request. | |
confidence | string | The confidence level of the lookup result.
|
|
suggestions_key | string | The suggestions key for address suggestion refinement. | |
suggestions_prompt | string | The prompt to display to the user, indicating what information they should enter next. | |
suggestions | collection | The collection of the suggestions that match the address search input. | |
global_address_key | string | The ID of the address matched as part of a search. | |
text | string | The suggestion that should be presented to the user as a possible match to their input. | |
matched | collection | A collection of the characters in the suggestion that have been matched. Integrators can use this information to highlight matched text. | |
format | string | The format URL of the suggested address. | |
dataset | string | The dataset of the suggestion. | |
additional_attributes | collection | The additional attributes of the suggestion. |
Name | Type | Description | |
---|---|---|---|
more_results_available | boolean | To indicate that there are more suggestions available than returned in this request. | |
confidence | string | The confidence level of the lookup result.
|
|
suggestions_key | string | The suggestions key for address suggestion refinement. | |
suggestions_prompt | string | The prompt to display to the user, indicating what information they should enter next. | |
suggestions | collection | The collection of the locality information that match the search key. | |
locality | object | The locality object consists 5 objects that represent 5 levels of locality information. Each level consists of a name , code , and description . The 5 levels are:
|
|
postal_code | object | The postal_code object consists of the following properties:
| |
addresses | collection | The collection of the addresses that match the search key. | |
global_address_key | string | The ID of the address matched as part of a lookup. | |
text | string | The address that should be presented to the user as a possible match to their input. | |
matched | collection | A collection of the characters in the address that have been matched. Integrators can use this information to highlight matched text. | |
format | string | The format URL of the suggested address. | |
dataset | string | The dataset of the address. |
The following response codes can be returned by the API:
Status Code | Reason phrase | Description |
---|---|---|
200 | Success | Request processed successfully. |
400 | Bad Request | Request failed due to malformed syntax. |
401 | Unauthorized | Auth-Token provided is incorrect. Sign in to the Self Service Portal to find the right token. |
403 | Forbidden | Request is not authorized to use this service. |
404 | Not Found | Request is not found. |
406 | Not Acceptable | Request is not in an acceptable format. |
408 | Request Timeout | Your request has timed out (the web server failed to respond in the specified time frame). Try submitting another request. If the issue persists, contact support. |
415 | Unsupported Media Type | You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value. |
429 | Too many requests | Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details. |
500 | Internal Server Error | An unexpected server error was encountered. Try submitting another request. If the issue persists, contact support. |
503 | Service Unavailable | Service unavailable. Check service status for up-to-date information. |
{
"country_iso": "GBR",
"datasets": [ "gb-additional-gas" ],
"key": {
"type": "default",
"value": "2481849308"
}
}
{
"result": {
"more_results_available": false,
"confidence": "Verified match",
"suggestions_key": "R0JHfjcuNzMweE1HQ",
"suggestions_prompt": "Enter selection",
"suggestions": [
{
"global_address_key": "R0JHfjcuNzMwbk9HQkdGQWpsQnd",
"text": "6 Valley View, Highley, BRIDGNORTH, Shropshire WV16 6EF",
"format": "https://api.experianaperture.io/address/format/v1/R0JHfjcuNzMwbk9HQkdGQWpsQnd",
"additional_attributes": [
{
"name": "picklist_display",
"value": "6 Valley View, Highley, BRIDGNORTH, Shropshire"
},
{
"name": "postcode",
"value": "WV16 6EF"
}
]
}
]
}
}
{
"country_iso": "AUS",
"datasets": [ "au-address" ],
"key": {
"type": "postal_code",
"value": "3071"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"region": {
"name": "VICTORIA",
"code": "VIC"
},
"town": {
"name": "Thornbury"
}
},
"postal_code": {
"full_name": "3071"
}
}
]
}
}
{
"country_iso": "AUS",
"datasets": [ "au-address-gnaf" ],
"key": {
"type": "locality",
"value": "thornb"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"region": {
"name": "VICTORIA",
"code": "VIC"
},
"town": {
"name": "Thornbury"
}
},
"postal_code": {
"full_name": "3071"
}
},
{
"locality": {
"region": {
"name": "QUEENSLAND",
"code": "QLD"
},
"town": {
"name": "Thornborough"
}
},
"postal_code": {
"full_name": "4871"
}
}
]
}
}
{
"country_iso": "GBR",
"datasets": [ "gb-address" ],
"key": {
"type": "postal_code",
"value": "Mk14"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"town": {
"name": "Milton Keynes"
},
"district": {
"name": "Linford Wood"
}
},
"postal_code": {
"full_name": "MK14 6NG"
}
},
{
"locality": {
"town": {
"name": "Milton Keynes"
},
"district": {
"name": "Linford Wood"
}
},
"postal_code": {
"full_name": "MK14 6GD"
}
}
]
}
}
{
"country_iso": "GBR",
"datasets": [ "gb-address" ],
"key": {
"type": "locality",
"value": "Neath Hill"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"town": {
"name": "Milton Keynes"
},
"district": {
"name": "Neath Hill"
}
},
"postal_code": {
"full_name": "MK14 6ER"
}
},
{
"locality": {
"town": {
"name": "Milton Keynes"
},
"district": {
"name": "Neath Hill"
}
},
"postal_code": {
"full_name": "MK14 6JH"
}
}
]
}
}
POST /address/lookup/v2/ HTTP/1.1
Add-Addresses: true
{
"country_iso": "GBR",
"datasets": [ "gb-address" ],
"key": {
"type": "udprn",
"value": "27453340"
}
}
{
"result": {
"more_results_available": false,
"confidence": "Verified match",
"suggestions": [
{
"locality": {
"town": {
"name": "York"
},
"district": {
"name": "Terrington"
}
},
"postal_code": {
"full_name": "YO60 6PH"
}
}
],
"addresses": [
{
"text": "1 North Ings Cottage, Terrington, York, YO60 6PH",
"matched": [],
"global_address_key": "aWQ9MSBOb3J0aCBJbmdzIENvdHRhZ2Us",
"format": "https://api.experianaperture.io/address/format/v1/aWQ9MSBOb3J0aCBJbmdzIENvdHRhZ2Us"
}
]
}
}
{
"country_iso": "USA",
"datasets": [ "us-address" ],
"key": {
"type": "postal_code",
"value": "10024"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"region": {
"code": "NY"
},
"sub_region": {
"name": "New York"
},
"town": {
"name": "New York"
}
},
"postal_code": {
"primary": "10024"
}
}
]
}
}
{
"country_iso": "USA",
"datasets": [ "us-address" ],
"key": {
"type": "locality",
"value": "bosto"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"region": {
"code": "MA"
},
"sub_region": {
"name": "Suffolk"
},
"town": {
"name": "Boston"
}
},
"postal_code": {
"primary": "02118"
}
},
{
"locality": {
"region": {
"code": "MA"
},
"sub_region": {
"name": "Suffolk"
},
"town": {
"name": "Boston"
}
},
"postal_code": {
"primary": "02241"
}
},
...
]
}
{
"country_iso": "USA",
"datasets": [ "us-address" ],
"key": {
"type": "locality",
"value": "boston, va"
}
}
{
"result": {
"more_results_available": false,
"confidence": "No matches",
"suggestions": [
{
"locality": {
"region": {
"code": "VA"
},
"sub_region": {
"name": "Culpeper"
},
"town": {
"name": "Boston"
}
},
"postal_code": {
"primary": "22713"
}
},
{
"locality": {
"region": {
"code": "VA"
},
"sub_region": {
"name": "Rappahannock"
},
"town": {
"name": "Boston"
}
},
"postal_code": {
"primary": "22713"
}
}
]
}