Data Quality user documentation
home/Address validation/Experian Address Validation/Address API reference/Lookup

Lookup

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.
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.

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 (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:
  • postal_code - Locality information is retrieved based on a supplied postal code.
  • locality - Locality information is retrieved based on a supplied locality like city or town.
  • udprn - Locality information is retrieved based on a supplied Unique Delivery Point Reference Numbers. (UK only)
value string Specify the search term 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.
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.
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 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:
  • region
  • sub_region
  • town
  • district
  • sub_district
Only elements that are populated will be returned.
postal_code object The postal_code object consists of the following properties:
  • full_name
  • primary
  • secondary
Only elements that are populated will be returned.
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.

United Kingdom

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

Australia

Request

{
  "country_iso": "AUS",
  "datasets": [ "au-address" ],
  "key": {
    "type": "postal_code",
    "value": "3071"
  }
}

Response

{
  "result": {
    "more_results_available": false,
    "confidence": "No matches",
    "suggestions": [
      {
        "locality": {
          "region": {
            "name": "VICTORIA",
            "code": "VIC"
          },
          "town": {
            "name": "Thornbury"
          }
        },
        "postal_code": {
          "full_name": "3071"
        }
      }
    ]
  }
}

Request

{
  "country_iso": "AUS",
  "datasets": [ "au-address-gnaf" ],
  "key": {
    "type": "locality",
    "value": "thornb"
  }
}

Response

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

United Kingdom

Request

{
  "country_iso": "GBR",
  "datasets": [ "gb-address" ],
  "key": {
    "type": "postal_code",
    "value": "Mk14"
  }
}

Response

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

Request

{
  "country_iso": "GBR",
  "datasets": [ "gb-address" ],
  "key": {
    "type": "locality",
    "value": "Neath Hill"
  }
}

Response

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

Request

POST /address/lookup/v2/ HTTP/1.1
Add-Addresses: true

{
  "country_iso": "GBR",
  "datasets": [ "gb-address" ],
  "key": {
    "type": "udprn",
    "value": "27453340"
  }
}

Response

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

United States

Request

{
  "country_iso": "USA",
  "datasets": [ "us-address" ],
  "key": {
    "type": "postal_code",
    "value": "10024"
  }
}

Response

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

Request

{
  "country_iso": "USA",
  "datasets": [ "us-address" ],
  "key": {
    "type": "locality",
    "value": "bosto"
  }
}

Response

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

Request

{
  "country_iso": "USA",
  "datasets": [ "us-address" ],
  "key": {
    "type": "locality",
    "value": "boston, va"
  }
}

Response

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

Address API reference