An address lookup is initiated by supplying a URL of the form.
- output indicates the required output format – currently this must be json
- maf is the identity of the Master Address File to which the lookup is applied
- parameters is a set of request parameters
Only a single request parameter is required – the query string. All other parameters are optional and should only be supplied when a non-default setting is required. As is standard with URLs, each parameter must be separated by an ampersand (&) character.
The query string is denoted by a single ‘q‘ character. This is the address search criteria, which can be anything from a single character up to a full address. Please note that the search criteria must be URL encoded.
It is good practice to avoid sending multiple requests whilst the user is entering the search criteria. Delaying the request by a fraction of a second (for example 500 milliseconds) after each input character will allow for faster data entry with the request being made when the user stops typing.
Example address lookup request for “Downing Street,London”.
This will return a pick-list of possible matches with the best predictions coming first. The client program would most likely reformat and present these to the end user as a list or tree. If the required address is not present then further input is needed to refine the list.
"ItemText": "Downing Street,London SW1A",
"ItemText": "Downing Court,Grenville Street,LONDON,WC1N",
When an item is selected the client program should continue the address lookup by specifying the item’s Sid (search identity) in the q (query string) parameter, along with any non-default options. Please note that the Sid is already URL encoded.
The previous two steps should be repeated until a single item is returned with the Selected field value true. When the Selected field is true the address lookup is complete and the requested output fields will be returned.
"Label1": "Prime Minister & First Lord of The Treasury",
"Label2": "10 Downing Street",
"Label4": "SW1A 2AA"
Each item in a pick-list contains three control flags:
- IsExpandable is true when the item can be expanded
- IsComplete is true when the item contains a complete address
- Selected is true when a single item has been selected and the requested output fields have been returned
Please note that an item can be either expandable or complete, but not both.