The /Picklist/refine endpoint is used in the Singleline, Typedown and Verification search types.
| 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. |
In the request body you can specify:
| Name | Type | Description | |
|---|---|---|---|
| refinement | string | The refinement text. | |
| 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. | |
| 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. |
| 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. |
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 | 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. |
