When a search has been performed by our service, the list of suggestions that is returned may contain suggestions where the multiple property is set to true. Should a user select one of these addresses, the user must be prompted to enter a refinement string.

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.

Path

Name Type Description
key string Key of the suggestion or list of suggestions you want to refine.
  • Use the returned suggestions_key to refine the whole list of suggestions, for example when choosing a single premises from multiple ranges.
  • Use the returned global_address_key if you prompted the user for more input after they selected a particular suggestion.

Body

Name Type Description
refinement string The refinement text.

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

Australia

Request

The /Suggestions/Refine method can be used in your addess validation workflow to filter a list of suggestions. A list of suggestions should be refined when the user enters text to be used to filter the response, creating a smaller set of results that contains more detail than the current item. For example, a response that contains a set of streets can be refined with the text "ba" to generate a new list of suggestions that only contains items beginning with the letters "ba".

Given the following response:

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "i5BQUFBQUFBQUFBQUFBQUFBQUFBLX4xM343",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "EuMGdVQUFRQUFBR0p5YVhOaVlXNWxBQS0tfjl-Nw",
        "text": "EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "EAST BRISBANE  QLD" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" },
          { "name": "alias_match", "value": "true" }
        ]
      },
      {
        "global_address_key": "UFBQUQuLjJRQUFBQUEuLi4uLndBQUFBQUFBQU",
        "text": "COORPAROO  QLD  4151",
        "additional_attributes": [
          { "name": "picklist_display", "value": "COORPAROO  QLD" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" },
          { "name": "alias_match", "value": "true" }
          { "name": "cross_border_match", "value": "true" },
        ]
      }
    ]
  }
}

The user needs to supply more input to get to the final address. You can use the returned suggestions_key to apply the refinement across all suggestions in the list or you can use the returned global_address_key to filter to a single suggestion first, before applying the refinement.
Suggestions containing the unresolvable_range attribute cannot be stepped into and need to be refined.

POST /address/suggestions/refine/v1/EuMGdVQUFRQUFBR0p5YVhOaVlXNWxBQS0tfjl-Nw HTTP/1.1

{
    "refinement": "ba"
}

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement depending on the refinement supplied.

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "osnfuJjdT-ergergUIGLKE54",
    "suggestions_prompt": "Enter street name or PO Box type",
    "suggestions": [
      {
        "global_address_key": "BQVltRUFBQUFBQUEtLX4xMX43",
        "text": "Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Balmoral Terrace" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "UFBQW5YTVNwaEJGR0FJWUFDQUFBQUFBQUFBQUFQLi5BQUFBQUFELi",
        "text": "Barker Street, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Barker Street" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "QVVTfjcuNzMwWk9BVVNI",
        "text": "Bates Court, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Bates Court" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Refine method can be used in your addess validation workflow to filter a list of suggestions. A list of suggestions should be refined when the user enters text to be used to filter the response, creating a smaller set of results that contains more detail than the current item. For example, a response that contains a range of building numbers can be refined with a number to select that address.

Given the following response:

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "QUFBQUFRbUZzYlc5eVlXd2dWR1Z5Y2",
    "suggestions_prompt": "Enter building number/name",
    "suggestions": [
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQX40Mn43",
        "text": "22 Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "22" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "QUFBQUFBQUFBQUF-MTF-Nw",
        "text": "24 ... 31 Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "24 ... 31" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

The user needs to supply more input to get to the final address. You can use the returned suggestions_key to apply the refinement across all suggestions in the list or you can use the returned global_address_key to filter to a single suggestion first, before applying the refinement.
Suggestions containing the unresolvable_range attribute cannot be stepped into and need to be refined.

POST /address/suggestions/refine/v1/QUFBQUFRbUZzYlc5eVlXd2dWR1Z5Y2 HTTP/1.1

{
    "refinement": "29"
}

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement depending on the refinement supplied.

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "TUNaaEJGZ0FJQUFBQUFBQUFBQUFELi53QU",
    "suggestions_prompt": "Enter building number",
    "suggestions": [
      {
        "global_address_key": "FBQUFBQU1qa0FBQUFBQUEtLX4xM343",
        "text": "29 Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "format": "https://api.experianaperture.io/address/format/v1/FBQUFBQU1qa0FBQUFBQUEtLX4xM343",
        "additional_attributes": [
          { "name": "picklist_display", "value": "29" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

United Kingdom

Request

The /Suggestions/Refine method can be used in your addess validation workflow to filter a list of suggestions. A list of suggestions should be refined when the user enters text to be used to filter the response, creating a smaller set of results that contains more detail than the current item. For example, a response that contains a set of streets can be refined with the text "mil" to generate a new list of suggestions that only contains items beginning with the letters "mil".

Given the following response:

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "R0JSfjcuNzMwTk1HQlJ",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQUFBQX41fjc",
        "text": "DOVER, Kent",
        "additional_attributes": [
          { "name": "picklist_display", "value": "DOVER, Kent" },
          { "name": "score", "value": "100" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "LjJRQUFBQUEuLi4uLndBQUFBQUFBQUF",
        "text": "Kearsney, DOVER, Kent",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Kearsney, DOVER, Kent" },
          { "name": "score", "value": "100" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

The user needs to supply more input to get to the final address. You can use the returned suggestions_key to apply the refinement across all suggestions in the list or you can use the returned global_address_key to filter to a single suggestion first, before applying the refinement.
Suggestions containing the unresolvable_range attribute cannot be stepped into and need to be refined.

POST /address/suggestions/refine/v1/BQUFBQUFBQUFBQUFBQUFBQX41fjc HTTP/1.1

{
    "refinement": "mil"
}

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement depending on the refinement supplied.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "R0JSfjcuNzMwVk9HQlJFZ0xtQndBQUFBQUJBQ",
    "suggestions_prompt": "Enter street, organisation or PO Box",
    "suggestions": [
      {
        "global_address_key": "VBQUFBQXNlbHVrWUFoZ0FJQUFBQUFB",
        "text": "Mill Close, DOVER, Kent",
        "format": "https://api.experianaperture.io/address/format/v1/VBQUFBQXNlbHVrWUFoZ0FJQUFBQUFB",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Mill Close" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "text": "Military Road, DOVER, Kent",
        "format": "https://api.experianaperture.io/address/format/v1/R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Military Road" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Refine method can be used in your addess validation workflow to filter a list of suggestions. A list of suggestions should be refined when the user enters text to be used to filter the response, creating a smaller set of results that contains more detail than the current item. For example, a response that contains a range of building numbers can be refined with a number to select that address.

Given the following response:

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "QUFBQUJBQUVBQUFBQW5IZmdVWUF",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "zTnlBeGNtWUFBQUFBQUEtLX43fjc",
        "text": "2 ... 14 Tilebourne Close, Upper Timsbury, ROMSEY, Hampshire SO51 0AH",
        "additional_attributes": [
          { "name": "picklist_display", "value": "2 ... 14   [even]" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "kjhTYufsLlid8ljhd",
        "text": "1 ... 13 Tilebourne Close, Upper Timsbury, ROMSEY, Hampshire SO51 0AH",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 ... 13   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

The user needs to supply more input to get to the final address. You can use the returned suggestions_key to apply the refinement across all suggestions in the list or you can use the returned global_address_key to filter to a single suggestion first, before applying the refinement.
Suggestions containing the unresolvable_range attribute cannot be stepped into and need to be refined.

POST /address/suggestions/refine/v1/QUFBQUJBQUVBQUFBQW5IZmdVWUF HTTP/1.1

{
    "refinement": "10"
}

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement depending on the refinement supplied.

{
  "result": {
    "more_results_available": true,
    "confidence": "Verified match",
    "suggestions_key": "R0JSfjcuNzMwc09HQlJFZ0xtQndBQU",
    "suggestions_prompt": "Enter building number",
    "suggestions": [
      {
        "global_address_key": "FBQUFBQUFNVEFBQVAuLkFBQUFBQUQuLi4uLkFBQ",
        "text": "10 Tilebourne Close, Upper Timsbury, ROMSEY, Hampshire SO51 0AH",
        "format": "https://api.experianaperture.io/address/format/v1/FBQUFBQUFNVEFBQVAuLkFBQUFBQUQuLi4uLkFBQ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

United States

Request

The /Suggestions/Refine method can be used in your addess validation workflow to filter a list of suggestions. A list of suggestions should be refined when the user enters text to be used to filter the response, creating a smaller set of results that contains more detail than the current item. For example, a response that contains a set of streets can be refined with the text "de" to generate a new list of suggestions that only contains items beginning with the letters "de".

Given the following response:

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "78JKHGiou23088djkhKHG987shgGBFd1",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "QUFBQUEuLi4uLndBQUFBQUFBQUFBQUFBQ",
        "text": "Richmond, Ocean Ridge FL 33435",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Richmond, Ocean Ridge FL" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "33435" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "zMwRVRVU0FEd1BtQndBQUFBQUNBUUFBQUFBQUFBRUFBQURmcU",
        "text": "Richmondville NY 12149",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Richmondville NY" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "12149" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

The user needs to supply more input to get to the final address. You can use the returned suggestions_key to apply the refinement across all suggestions in the list or you can use the returned global_address_key to filter to a single suggestion first, before applying the refinement.
Suggestions containing the unresolvable_range attribute cannot be stepped into and need to be refined.

POST /address/suggestions/refine/v1/zMwRVRVU0FEd1BtQndBQUFBQUNBUUFBQUFBQUFBRUFBQURmcU HTTP/1.1

{
    "refinement": "de"
}

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement depending on the refinement supplied.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "cUJ3QUFBQUFBRkpKUTBoTlQwNUVBQS0tfjExfjc",
    "suggestions_prompt": "Enter street name, organisation or PO Box type",
    "suggestions": [
      {
        "global_address_key": "d2doR0FJWUFDQUFBQUFBQUFBQUF",
        "text": "Decker Rd, Richmondville NY 12149",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Decker Rd, Richmondville NY" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "12149" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "RnpBQUFBQUFBLX4xMX43",
        "text": "Depot St, Richmondville NY 12149",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Depot St, Richmondville NY" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "12149" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Refine method can be used in your addess validation workflow to filter a list of suggestions. A list of suggestions should be refined when the user enters text to be used to filter the response, creating a smaller set of results that contains more detail than the current item. For example, a response that contains a range of building numbers can be refined with a number to select that address.

Given the following response:

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "VVNBfjcuNzMwaE9VU0FEd1BtQndBQUFBQUJBQUVB",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "ndBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQX4yNH43",
        "text": "10001 ... 10099 Charles St, Richmond IL 60071-9589",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10001 ... 10099   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9589" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "VVNBfjcuNzMwdk9VU0FEd1BtQndBQUFBQUJBZ0V",
        "text": "10101 ... 10199 Charles St, Richmond IL 60071-9590",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10101 ... 10199   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9589" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      }
    ]
  }
}

The user needs to supply more input to get to the final address. You can use the returned suggestions_key to apply the refinement across all suggestions in the list or you can use the returned global_address_key to filter to a single suggestion first, before applying the refinement.
Suggestions containing the unresolvable_range attribute cannot be stepped into and need to be refined.

POST /address/suggestions/refine/v1/SnNaWE1nVTNSeVpXVjBMQ0JTU1VOSVRVOU9SQUFBQUFBQX4yNH43 HTTP/1.1

{
    "refinement": "10111"
}

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement depending on the refinement supplied.

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "BQUFBQX4yOX43",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMwTk9VU0FEd1BtQnd",
        "text": "10111 Charles St, Richmond IL 60071-9590",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMwTk9VU0FEd1BtQnd",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10111" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9590" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}