The /search endpoint is used in the Autocomplete, Singleline and Typedown search types.

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.
Transliterate (optional) bool Determines whether transliteration from the native script to the Latin script will be performed. By default, it is set to false, meaning no transliteration will occur. If set to true, transliteration will be performed.

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).
max_suggestions
(Optional)
integer The maximum number of suggestions you want to get returned. You can get up to 100 addresses returned. The default value of this setting is 7.
components object Object defining the input components.
unspecified collection Collection of unspecified text inputs.
options collection Additional options. See options for more detailed information.
The optional options object is required when using the Singleline or Typedown search type. You don't need to pass an options array when using the Autocomplete search type.
location
(Optional)
string Geographical location (latitude, longitude) to use as the center point for the search (USA only).
preferred_language
(Optional)
collection Valid only for country JPN, dataset jp-address-ed.
The results are returned in the desired languages (in the order of preference).
Currently the only valid language is ja (which is required to be set in order for preferred_script to work).
preferred_script
(Optional)
collection Valid only for country JPN, dataset jp-address-ed
The suggestions text will be using the desired script option (in the order of preference).
Setting this requires validly set preferred_language.
Possible script values:
  • latin - Latin (e. g. '2 CHŌME')
  • preserve_input - detects the input script and returns the suggestions in detected script. If the input contains mixed script, the result will be in the default script for the specified language, (e. g. Kanji for JA language

Options

Name Type Description
search_type string Defines which search type to use:
  • Singleline - This search type is optimized for users entering two or more address elements, each separated by a comma, in the order as they would appear on an envelope.
  • Typedown - This search type is optimized for users to start searching with the most general address element and, once that has been found, move on to more specific parts of the address.
flatten
(Optional)
string Defines whether the search results will be 'flattened' to a single list of deliverable results, or output a list of suggestions that can be stepped into.
  • True - The list of suggestions will contain an item per address.
  • False - The list of suggestions might contain items that cover more than one address, for example as range of building numbers that need to be refined further to retrieve a final address.
The default value of this setting is True.
intensity
(Optional)
string Defines how hard the search engine will work to obtain a match. Higher intensity values may yield more results than lower intensity values, but will also result in longer search times. The available values are:
  • Exact - This does not allow many mistakes in the search term, but is the fastest.
  • Close - This allows some mistakes in the search term, and is the default setting.
  • Extensive - This allows many mistakes in the search term, and will take the longest.
The default value of this setting is Close.
prompt_set
(Optional)
string An address can be submitted as one or as many fields; the prompt_set property defines which address elements can be entered in each field, for example a field might be constrained so that it only accepts postcodes. The prompt set definition depends on the search type used.
You can view the definitions by using the Prompt sets API request. The available values are:
  • OneLine - All search text to be submitted upon a single line.
  • Default - The default prompt set for the engine.
  • Generic - A general data-independent prompt set.
  • Optimal - Requires the minimum possible amount of search text to perform a search.
  • Alternate - An extended country-specific set for where the information required for an optimal search is not available.
  • Alternate2 - A different alternative prompt set (USA only).
The default value of this setting is Default.

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.
204 No Content Request processed successfully, but there is no content to be returned.
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 us.
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 us.
503 Service Unavailable Service unavailable. Check service status for up-to-date information.

Australia

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "56 Queens R"
    ]
  },
  "datasets": [ "au-address-gnaf" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "FBQS0kJCR-UUw9MTE",
        "text": "56 Queens Road, ASQUITH  NSW 2077",
        "matched": [],
        "format": "https://api.experianaperture.io/address/format/v1/FBQS0kJCR-UUw9MTE"
      },
      {
        "global_address_key": "aWQ9NTYgUXVlZW5zIFJv",
        "text": "56 Queens Road, FIVE DOCK  NSW 2046",
        "matched": [],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9NTYgUXVlZW5zIFJv"
      }
    ]
  }
}

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "55/49 Queens Road, five dock"
    ]
  },
  "datasets": [ "au-address-datafusion" ],
  "options": [
    {
      "name": "search_type",
      "value": "singleline"
    },
    {
      "name": "prompt_set",
      "value": "optimal"
    }
  ]
}

Response

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "QVVFfjcuNzMwQk1BVUVIQUxtQndBQUFBQUJBUUVBQVFBQ",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
        "text": "Unit 55  49-51 Queens Road, FIVE DOCK  NSW  2046",
        "format": "https://api.experianaperture.io/address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Unit 55  49-51 Queens Road, FIVE DOCK  NSW" },
          { "name": "score", "value": "86" },
          { "name": "postcode", "value": "2046" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "melbourne"
    ]
  },
  "datasets": [ "au-address" ],
  "options": [
    {
      "name": "search_type",
      "value": "typedown"
    }
  ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_prompt": "Enter postcode or place",
    "suggestions": [
      {
        "global_address_key": "dWc1ltOTFjbTVsQUEtLX45fjc",
        "text": "Melbourne",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Melbourne" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "cuNzMwNFRBVVNIQVBtQndBQUFBQUN",
        "text": "Melbourne Airport",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Melbourne Airport" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "YkdKdmRYSnVaUUEtfjl-Nw",
        "text": "Melbourne City Mail Centre",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Melbourne City Mail Centre" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" },
          { "name": "alias_match", "value": "true" }
        ]
      }
    ]
  }
}

United Kingdom

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "160 bla"
    ]
  },
  "datasets": [ "gb-address" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "aWQ9MTYwIEJsYWtlIEF2ZW51Z",
        "text": "160 Blake Avenue, Barking, IG11 9SD",
        "matched": [[18, 20], [4, 8], [0, 3]],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MTYwIEJsYWtlIEF2ZW51Z"
      },
      {
        "global_address_key": "aWQ9MTYwIEJsYWNrIFJvYWQsIE1hY2",
        "text": "160 Black Road, Macclesfield, SK11 7LF",
        "matched": [[4, 8], [0, 3]],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MTYwIEJsYWNrIFJvYWQsIE1hY2"
      }
    ]
  }
}

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "160, SE1 8EZ"
    ]
  },
  "datasets": [ "gb-additional-business" ],
  "options": [
    {
      "name": "search_type",
      "value": "singleline"
    },
    {
      "name": "prompt_set",
      "value": "optimal"
    }
  ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "R1g2fjcuNzMwQlNHWDZDZ3psQndBQUFBQUJBVEUyTUN3Z1UwVXhJRGhGV2dBcUF3QUF-MTJ-Nw",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
        "text": "Experian, 160 Blackfriars Road, LONDON SE1 8EZ",
        "format": "https://api.experianaperture.io/address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Experian, 160 Blackfriars Road, LONDON" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "SE1 8EZ" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "London"
    ]
  },
  "datasets": [ "gb-additional-multipleresidence" ],
  "options": [
    {
      "name": "search_type",
      "value": "typedown"
    }
  ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_prompt": "Enter postcode or place",
    "suggestions": [
      {
        "global_address_key": "R1g2fjcuNzMwMlRHWDZDZ3psQndBQUFBQUNBUUFBQUFBQUFBUUFBQUFGTkMwQk",
        "text": "LONDON",
        "additional_attributes": [
          { "name": "picklist_display", "value": "London" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "R1g2fjcuNzMwQ1RHWDZDZ3psQndBQUFBQUNBUUFBWUFBQUFBTUFBd0J2U0I4QU",
        "text": "London Apprentice",
        "additional_attributes": [
          { "name": "picklist_display", "value": "London Apprentice" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

United States

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "20 main"
    ]
  },
  "datasets": [ "us-address" ],
  "location": "34.036352, -118.209649"
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "aWQ9MjAgTWFpbiBTdCwgVml",
        "text": "20 Main St, Vista CA 92083",
        "matched": [[3, 7], [0, 2]],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MjAgTWFpbiBTdCwgVml"
      },
      {
        "global_address_key": "aWQ9MjAgTWFpbiBTdCBTdGUgMTI1L",
        "text": "20 Main St Ste 125, Vista CA 92083",
        "matched": [[3, 7], [0, 2]],
        "format": "https://api.experianaperture.io/address/format/v1/aWQ9MjAgTWFpbiBTdCBTdGUgMTI1L"
      }
    ]
  }
}

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "20 Main St, Ste 125, Vista"
    ]
  },
  "datasets": [ "us-address" ],
  "options": [
    {
      "name": "search_type",
      "value": "singleline"
    },
    {
      "name": "prompt_set",
      "value": "optimal"
    }
  ]
}

Response

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "VVNBfjcuNzMwSU1VU0FEd1BtQndBQUFBQUJBUUVBQVFBQUFBRVgucm5RQ0NFWUFoTV",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "text": "20 Main St Ste 125, Vista CA 92083-5847",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "20 Main St Ste 125, Vista CA" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "92083-5847" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "Miami"
    ]
  },
  "datasets": [ "us-address" ],
  "options": [
    {
      "name": "search_type",
      "value": "typedown"
    }
  ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_prompt": "Enter ZIP code, city name, county name or state code",
    "suggestions": [
      {
        "global_address_key": "NFaXhrQUF3QUFBRTFwWVcxcEFBLS1-NX43",
        "text": "Miami",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Miami" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "UJ1aWhrQUFnQUFBRTFwWVcxcEFBLS1-NX43",
        "text": "Miami Beach",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Miami Beach" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}