The /lookup endpoint is used in the Lookup search type.

Headers

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.

Body parameters

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.
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 key for your lookup.

Headers

Name Type Description
Reference-Id
(Optional)
String Identifier that was supplied by you in the request header to help you track the request.

Body

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.
  • Verified match: The input was matched to a single deliverable address in our data. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Multiple matches: The input was matched to more than one deliverable address in our data. This can happen when the provided address doesn't contain enough information to return just one match. As a result, the returned addresses may or may not be deliverable addresses. Therefore, a list of suggestions containing all the matches will be returned and the user has to select the required address.
  • Too many matches: The input was too broad and matched too many addresses in our data. The user should be further prompted to provide additional information.
  • Interaction required: The input was matched to a single deliverable address in our data. However, user interaction is recommended as the confidence in the validity of this address is not high enough for it to be classed as a *Verified match*.
  • Premises partial: The input was partially matched to a deliverable address in our data. For example, a search on "Flat A, 63 Southerton Road, London" could be matched to "63 Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Street partial: The input was partially matched to a deliverable address in our data. For example, a search on "63 Southerton Road, London" could be matched to "Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Verified place: The input was matched to a single deliverable address in our data but the street information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Verified street: The input was matched to a single deliverable address in our data but the building information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Incomplete address: The input was matched to an address in our data, but is not deliverable. This is commonly returned when searching within data that does not contain building level information. If the user selects a suggestion with this attribute set, then they should be further prompted to provide additional building level information so that the address is deliverable.
  • Insufficient search terms: The input did not contain enough characters to provide a meaningful result.
  • No matches: The input could not be matched to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.
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.

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.
403 Forbidden Request is not authorized to use this service.
406 Not Acceptable Request is not in an acceptable format.
408 Request Timeout Response was not returned within the timeout allowance.
415 Unsupported Media Type Request is not using a Media type that is recognized by the server.
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 The server has encountered an error.
503 Service Unavailable Service unavailable. Check service status for up-to-date information.

Request

{
  "country_iso": "GBR",
  "datasets": [ "gb-additional-gas" ],
  "key": {
    "type": "default",
    "value": "2481849308"
  }
}

Response

{
  "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"
          }
        ]
      }
    ]
  }
}