The /search endpoint is used in the Autocomplete, Singleline and Typedown search types.
| 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. |
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:
|
|
| Name | Type | Description |
|---|---|---|
| search_type | string | Defines which search type to use:
|
| 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.
|
| 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:
|
| 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:
|
| Name | Type | Description |
|---|---|---|
| Reference-Id (Optional) |
string | Identifier that was supplied by you in the request header to help you track the request. |
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.
|
|
| 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. |
{
"country_iso": "AUS",
"components": {
"unspecified": [
"56 Queens R"
]
},
"datasets": [ "au-address-gnaf" ]
}
{
"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"
}
]
}
}
{
"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"
}
]
}
{
"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" }
]
}
]
}
}
{
"country_iso": "AUS",
"components": {
"unspecified": [
"melbourne"
]
},
"datasets": [ "au-address" ],
"options": [
{
"name": "search_type",
"value": "typedown"
}
]
}
{
"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" }
]
}
]
}
}
{
"country_iso": "GBR",
"components": {
"unspecified": [
"160 bla"
]
},
"datasets": [ "gb-address" ]
}
{
"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"
}
]
}
}
{
"country_iso": "GBR",
"components": {
"unspecified": [
"160, SE1 8EZ"
]
},
"datasets": [ "gb-additional-business" ],
"options": [
{
"name": "search_type",
"value": "singleline"
},
{
"name": "prompt_set",
"value": "optimal"
}
]
}
{
"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" }
]
}
]
}
}
{
"country_iso": "GBR",
"components": {
"unspecified": [
"London"
]
},
"datasets": [ "gb-additional-multipleresidence" ],
"options": [
{
"name": "search_type",
"value": "typedown"
}
]
}
{
"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" }
]
}
]
}
}
{
"country_iso": "USA",
"components": {
"unspecified": [
"20 main"
]
},
"datasets": [ "us-address" ],
"location": "34.036352, -118.209649"
}
{
"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"
}
]
}
}
{
"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"
}
]
}
{
"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" }
]
}
]
}
}
{
"country_iso": "USA",
"components": {
"unspecified": [
"Miami"
]
},
"datasets": [ "us-address" ],
"options": [
{
"name": "search_type",
"value": "typedown"
}
]
}
{
"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" }
]
}
]
}
}