Picklist/Stepin

The /Picklist/stepin endpoint is used in the Singleline, Typedown and Verification search types.

Headers

Name Type Description
Monikers
(Optional)
string This is the moniker that will have the action performed upon it.
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
layout string This contains the set of layouts that are valid.
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 collection Additional options. See options for more detailed information.

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.

Headers

Name Type Description
Monikers
(Optional)
string This is the moniker that will have the action performed upon it.
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.

Picklists

The picklist elements of the /Picklist/stepin 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
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.