Data Quality user documentation
home/Address validation/Pro Web/API reference (REST)/Search

Search

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

Headers

Name Type Description
Timeout-Seconds
(Optional)		 integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 1-60. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.
Diagnostics
(Optional)		 boolean Enable diagnostic info

The default value of this setting is False.

Body parameters

In the request body you can specify:

Name Type Description
dataset_code string The identifier of the dataset you are using for this search.
engine 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.
  • Verification - This search type is optimized for users entering the complete address, as it would appear on an envelope.
  • Keyfinder - This search type is designed to enable the user to enter a key search term to produce desired address information.
  • Intuitive - This search type is optimized to search as a user types.
layout string This contains the set of layouts that are valid.
options collection Additional options. See options for more detailed information.
components object Object defining the input components.
unspecified string Collection of unspecified text inputs.
format_picklist_items boolean This specifies whether final addresses should be returned with picklist entries. Searches may be slower with this option, but another server request may not be required.

The default value of this setting is False.

Options

Name Type Description
engine_timeout integer Allows you to limit Intuitive engine results to certain values of address element.
The default value of this setting is True.
threshold integer This defines the threshold that is used to decide whether results will be returned in the picklist, or whether an informational picklist result will be returned, requiring further refinement.This element is only relevant when using hierarchical mode.
The standard setting is 25 items.
flatten boolean 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.
constraint string Allows you to limit Intuitive engine results to certain values of address element.
intensity 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.
picklist_size integer Defines the number of results that will be returned by the Singleline search (any further matches will be truncated). The minimum value that can be assigned is 1 and the maximum is 100. When no value is set (or is 0), this setting will not be applied.
prompt_set 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
Timeout-Seconds
(Optional)		 integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 1-60. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.
Diagnostics
(Optional)		 boolean Enable diagnostic info

The default value of this setting is False.

Body

The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.

Confidence

The confidence level of the Search result are:

Name Type Description
verified string 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 string 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.
Interaction required string 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 string 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 string 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 string 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 string 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.
Place partial string The input was matched to a single deliverable address in our data but some 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.
NA string The input could not be matched as results are not available. Therefore, address validation is not possible and the address provided by the user should be used.
None string The input could not be matched as it does not exist to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.

Validation detail

The validation_detail elements of the Search result are:

Name Type Description
buidling_firm_name_corrected boolean Building or Firm name has been added or changed.
primary_number_corrected boolean Primary Number has been added or changed.
street_corrected boolean Street has been (non-trivially) corrected.
rural_route_highway_contract_matched boolean Rural Route or Highway Contract has been matched.
city_name_corrected boolean City name has been added or changed.
city_name_alias_matched boolean City name has been alias matched.
state_corrected boolean State or Province has been added or changed.
zip_code_corrected boolean Post code has been added or corrected.
secondary_num_retained boolean Secondary number has been retained.
iden_pre_st_info_retained boolean Identifiable pre-street information has been retained
gen_pre_st_info_retained boolean General pre-street information has been retained.
post_st_info_retained boolean Post-street information has been retained.

Address

The address elements of the Search result are:

Name Type Description
address_lines collection Collection of address lines.
label string This defines a text label for the line, which will describe the contents of the line.
line string This defines the final formatted address line, as described by the layout that was used to format the address result.
has_overflown_to_other_line boolean This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines.
line_content string This describes the elements that are found upon the address line. For example "Name". The following values may be returned:
  • none: There was no content specified for this line.
  • address: There are address elements specified upon this line.
  • name: There is name information specified upon this line.
  • ancillary: There is ancillary data specified upon this line.
  • dataplus: There is DataPlus information specified on this line.
is_truncated boolean This element signifies that some address elements were truncated.
has_overflow_lines boolean This element signifies that at least one line in the layout has overflown onto other lines.
has_truncated_lines boolean This element signifies that at least one line in the layout was truncated.
dpv_status string The dpv status of the Search result are:
  • DPVNotConfigured: DPV is not configured for this combination of data mapping/engine/layout.
  • DPVConfirmed: All address components (primary and secondary) are DPV confirmed.
  • DPVConfirmedMissingSec: Primary number was DPV confirmed but secondary is incorrect or missing.
  • DPVNotConfirmed: Primary number was not DPV confirmed.
  • DPVLocked: DPV retrieval has been locked by a previous search on a seed address.
  • DPVSeedHit: This address is a seed address. DPV retrieval has been locked an an unlock code must be supplied to reactivate it.
has_missing_sub_premise boolean This attribute indicates that the address is a large volume receiver and may be missing subpremises information.

Picklists

The picklist elements of the Search result are:

Name Type Description
moniker string This is the SPM (Search Point Monikers) that can be used to replicate the given picklist.
prompt string This defines a short text prompt that may be displayed to the user in an interactive scenario.
potential_matches integer If more matches than the specified picklist threshold exist, this value can be used as an estimate of the total number of available matches.
auto_format_safe boolean Searches that return a single deliverable result will have this element set to TRUE.
auto_format_past_close boolean Searches that return a single deliverable result, but also produce other lesser matches, will have this element set to TRUE.
auto_stepin_safe boolean Searches that return a single non-deliverable result that can be stepped into will have this element set to TRUE.
auto_stepin_past_close boolean Searches that return a single non-deliverable result that can be stepped into, but that also produce other lesser matches, will have this element set to TRUE.
large_potential boolean Searches that return too many results to be contained in a picklist will have this element set to TRUE.
max_matches boolean Searches that produce more than the maximum number of matches allowed will have this element set to TRUE.
more_other_matches boolean Searches that produce in excess of the picklist threshold may return a subset of the matches in the picklist, plus an informational picklist item that allows the user to access the others. In this situation, this element is set to TRUE.
over_threshold boolean Searches that produce in excess of the picklist threshold may only return a single informational picklist item that allows the user to access the full results. In this situation, this element is set to TRUE.
can_flatten boolean This defines whether the search results will be 'flattened' to a single picklist of deliverable results, or output as (potentially multiple) hierarchical picklists of results that can be stepped into.
picklist object Object containing the picklist.
moniker string This is the SPM (Search Point Monikers) that can be used to perform actions upon the picklist item, such as stepping in or formatting the item into a final address.
partial_address string This picklist item is partially formatted into a single string, which may be useful for display in user interactive environments. This string is not suitable to be displayed as the picklist text: the Picklist element must be used instead.
picklist_text string This is the string that must be displayed to the user for the picklist text.
postcode string This is a postcode string and should be used in conjunction with the Picklist element, defined previously, for the picklist text. This string is for display purposes only, and may be returned blank if no postcode is associated with the picklist string.
score integer This is the percentage score that is given to each match returned from a search. This can be used as a guide to the quality of the match produced.
formatted_address integer This is the full formatted address for the picklist entry. This will be null if the search was submitted without the FormattedAddressInPicklist option set, or if the picklist entry does not correspond to a full formatted address.
full_address boolean This element signifies that the picklist item represents a deliverable address. If the user selects this picklist item, then it should be formatted into a final address, indicating the end of the address capture process.
multiple boolean This element signifies that the picklist item represents multiple addresses, merged into a single entry.
can_step boolean This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item can be stepped into, to produce a new picklist with more detail.
alias_match boolean This element signifies that the picklist item has been produced by a match to an alias of the item. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required.
postcode_recoded boolean This element signifies that a postcode was searched on, and that the match was made to a newer recoded version of the postcode. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required.
cross_border_match boolean This element signifies that a place such as a town was searched upon, and that the match was made to an adjacent place.
dummy_pobox boolean This element is only relevant when searching with the engine option Flatten set to FALSE.
has_name boolean This element is only relevant when searching within data mappings that contain Names information, such as GBN.
informational boolean This element is only relevant when searching with the engine option Flatten set to FALSE.
info_warning boolean This element signifies that the picklist item is a warning informational item.
incomplete boolean This element signifies that the picklist item does not contain all of the information required to make it a deliverable address. This is commonly returned when searching within data mappings that do not contain premises information.
unresolvable_range boolean This element signifies that the picklist item is a range of premises which cannot be expanded, due to a lack of information about the possible elements within the range.
phantom_primary_point boolean This element is only relevant when searching within the AUS data. This element signifies that the picklist item is a phantom primary point.

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.
408 Request Timeout Response was not returned within the timeout allowance.
500 Internal Server Error The server has encountered an error.
Pro Web

API reference (REST)