Astun have set up a National Address Search web service, which is based on the standard Address Search Request used by iShare. The National Address Search service has been populated with national coverage of AddressBase® Premium data. At present it is provided on a beta service
This service is hosted by an EC2 Instance using an iShareData Astun database as a Data Share and an osdata database as the source. The data is then scheduled to refresh at a chosen day and time.
Usage
Customers will be provided with a dedicated endpoint which allows Astun to manage and track access via an API Gateway:
https://services.astuntechnology.com/v1/yourcouncil-gov-uk/data/addressbase/locationsearch?
The endpoint will be configured with basic authentication based on those used in the iShare GIS Print to PDF and WPS service requests.
...
Requests are made in the following form (for example searching on the postcode NW1 6XE)
https://go.yourcouncil.gov.uk/nlpgservices.astuntechnology.com/v1/yourcouncil-gov-uk/data/addressbase/locationsearch?pagesize=10&startnum=1&location=NW1%206XE
...
Performing this request will return JSON formatted results with all the first N addresses contained within that postcode (N being the pagesize, in this case 10).
|
Input Parameters
The following Parameters can be passed into the Search Requests:
...
Parameter Name
...
Requirement
...
Description
...
pagesize
...
mandatory
...
This is the number of results that you wish to return
...
startnum
...
mandatory
...
This would be 1 the first time that you made a call and then, if the maximum number of results requested were returned you would then make another call with the same information only specifying a startnum = pagesize +1 etc.
...
location
...
mandatory
...
The address that you wish to search for or a UPRN. In the above example we wish to return all addresses that contain NW1 6XE
...
gettotals
...
optional
...
false
(default) or true
: Whether to include the total number of results returned by the search, requests with totals will be significantly slower. When false, the search will still include the totals
field, but with a value of 0
(zero).
Output Columns
The following columns are returned in the results
...
Name
...
Description
...
UniqueId
...
The Unique Property Reference Number (UPRN) from Address Base
...
Parent
...
The Unique Street Reference Number (USRN) from Address Base for the street the address is located on.
...
DisplayName
...
The formatted address string. Display name includes a <b> HTML element to highlight the input search term.
...
Type
...
The type of address.
...
X
...
The Easting in British National Grid coordinates
...
Y
...
The Northing in British National Grid coordinates
...
Rank
...
The accuracy of the match. The higher the higher the percentage match of output string to input string
...
Name
...
The formatted address string.
...
Zoom
...
A zoom level. This can be ignored (as it is included for historic reasons) and for the national search which will always return 100.
...
BS7666 fields
...
Standard BS7666 fields are also returned with the results:
bs7666_organisation
bs7666_sao_text
bs7666_sao_start_number
bs7666_sao_start_suffix
bs7666_sao_end_number
bs7666_sao_end_suffix
bs7666_pao_text
bs7666_pao_start_number
bs7666_pao_start_suffix
bs7666_pao_end_number
bs7666_pao_end_suffix
bs7666_street_description
bs7666_locality
bs7666_town_name
bs7666_administrative_area
bs7666_postcode_locator
bs7666_saon
bs7666_paon
Other Examples
Using Postcode
The search algorithm is based on string matching, but with preference given to the postcode substring. For best results, the full postcode should always be used where possible and known, in combination with another unique element of the address string. As per the examples below
...
Search string
...
Data returned in JSON
...
215 NW1 6XE
...
Code Block |
---|
[
"10033619968",
"8401123",
"Sweet & Liberty, 215 Baker Street, London, NW1 6XE",
"Property",
"527870.4",
"182081.17",
"23%",
"Sweet & Liberty, 215 Baker Street, London, NW1 6XE",
"100",
"SWEET & LIBERTY",
"",
"",
"",
"",
"",
"",
"215",
"",
"",
"",
"BAKER STREET",
"",
"LONDON",
"",
"NW1 6XE",
"",
"215",
"5990",
"City of Westminster"
] |
...
Flat 10 NW1 6XE
...
Code Block |
---|
[
"10033619980",
"8401123",
"Flat 10, 219 Baker Street, London, NW1 6XE",
"Property",
"527868.08",
"182090.78",
"38%",
"Flat 10, 219 Baker Street, London, NW1 6XE",
"100",
"",
"FLAT 10",
"",
"",
"",
"",
"",
"219",
"",
"",
"",
"BAKER STREET",
"",
"LONDON",
"",
"NW1 6XE",
"FLAT 10",
"219",
"5990",
"City of Westminster"
] |
...
Bay Oil NW1 6XE
...
Code Block |
---|
[
"10033529251",
"8401123",
"Bay Oil Supply Co Ltd, Baker Street, London, NW1 6XE",
"Property",
"527845",
"182149",
"30%",
"Bay Oil Supply Co Ltd, Baker Street, London, NW1 6XE",
"100",
"",
"",
"",
"",
"",
"",
"BAY OIL SUPPLY CO LTD",
"",
"",
"",
"",
"BAKER STREET",
"",
"LONDON",
"",
"NW1 6XE",
"",
"BAY OIL SUPPLY CO LTD",
"5990",
"City of Westminster"
] |
NOTE: In the above examples, spaces are not necessary in the postcode, and searches with NW16XE will also work. Results can become a bit more spurious with other spacing. For example whilst "215 NW1 6XE" identifies the specific property, but "215 NW 16 XE" returns all properties in the postcode.
Without Postcode
Where postcode is not known or is only partially known the search engine will aim to identify the best fit possible, as per the examples below.
Search String
Data returned in JSON
219 Baker Street London
Code Block |
---|
[
"10033619969",
"8401123",
"219 Baker Street, London, NW1 6XE",
"Property",
"527868.08",
"182090.78",
"77%",
"219 Baker Street, London, NW1 6XE",
"100",
"",
"",
"",
"",
"",
"",
"",
"219",
"",
"",
"",
"BAKER STREET",
"",
"LONDON",
"",
"NW1 6XE",
"",
"219"
] , [
"10033619971",
"8401123",
"Flat 1, 219 Baker Street, London, NW1 6XE",
"Property",
"527868.08",
"182090.78",
"65%",
"Flat 1, 219 Baker Street, London, NW1 6XE",
"100",
"",
"FLAT 1",
"",
"",
"",
"",
"",
"219",
"",
"",
"",
"BAKER STREET",
"",
"LONDON",
"",
"NW1 6XE",
"FLAT 1",
"219",
"5990",
"City of Westminster"
] |
Liberty Baker Street
Code Block |
---|
[
"10033619968",
"8401123",
"Sweet & Liberty, 215 Baker Street, London, NW1 6XE",
"Property",
"527870.4",
"182081.17",
"46%",
"Sweet & Liberty, 215 Baker Street, London, NW1 6XE",
"100",
"SWEET & LIBERTY",
"",
"",
"",
"",
"",
"",
"215",
"",
"",
"",
"BAKER STREET",
"",
"LONDON",
"",
"NW1 6XE",
"",
"215",
"5990",
"City of Westminster"
] |
Liberty NW1
|
Input Parameters
The following Parameters can be passed into the Search Requests:
Parameter Name | Requirement | Description |
---|---|---|
| mandatory | This is the number of results that you wish to return |
| mandatory | This would be 1 the first time that you made a call and then, if the maximum number of results requested were returned you would then make another call with the same information only specifying a startnum = pagesize +1 etc. |
| mandatory | The address that you wish to search for or a UPRN. In the above example we wish to return all addresses that contain NW1 6XE |
| optional |
|
Output Columns
The following columns are returned in the results
Name | Description |
---|---|
| The Unique Property Reference Number (UPRN) from Address Base |
| The Unique Street Reference Number (USRN) from Address Base for the street the address is located on. |
| The formatted address string. Display name includes a <b> HTML element to highlight the input search term. |
| The type of address. |
| The Easting in British National Grid coordinates |
| The Northing in British National Grid coordinates |
| The accuracy of the match. The higher the higher the percentage match of output string to input string |
| The formatted address string. |
| A zoom level. This can be ignored (as it is included for historic reasons) and for the national search which will always return 100. |
BS7666 fields | Standard BS7666 fields are also returned with the results:
|
Other Examples
Using Postcode
The search algorithm is based on string matching, but with preference given to the postcode substring. For best results, the full postcode should always be used where possible and known, in combination with another unique element of the address string. As per the examples below
Search string | Data returned in JSON | ||
---|---|---|---|
215 NW1 6XE |
| ||
Flat 10 NW1 6XE |
| ||
Bay Oil NW1 6XE |
|
NOTE: In the above examples, spaces are not necessary in the postcode, and searches with NW16XE will also work. Results can become a bit more spurious with other spacing. For example whilst "215 NW1 6XE" identifies the specific property, but "215 NW 16 XE" returns all properties in the postcode.
Without Postcode
Where postcode is not known or is only partially known the search engine will aim to identify the best fit possible, as per the examples below.
Search String | Data returned in JSON | ||
---|---|---|---|
219 Baker Street London |
| ||
Liberty Baker Street |
| ||
Liberty NW1 |
|
There is however no further "intelligence" in the search matching. For example if the search is done on Baker Road London (which does not exist), it would not consider Baker Street to be a better match, but would prefer addresses that included the word "Baker" and "Road" in the address string, as per the example below (which returns multiple other addresses).
Search String | Data returned in JSON | ||
---|---|---|---|
215 Baker Road London |
|
|
|
|
|
|
|
|
There is however no further "intelligence" in the search matching. For example if the search is done on Baker Road London (which does not exist), it would not consider Baker Street to be a better match, but would prefer addresses that included the word "Baker" and "Road" in the address string, as per the example below (which returns multiple other addresses).
Search String
Data returned in JSON
215 Baker Road London
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Integration and IP Whitelisting
...
The Council is responsible for ensuring that any contractors are fully compliant with OS Licensing arrangements for AddressBase Premium and legal obligations from those licence arrangements. The service should only be used for Council specific work, and not for any other address searches by the contractors with whom the Council are engaged.
Future enhancements
Over the course of the beta period Astun may wish to introduce:
...
An upper limit to the pagesize of inbound requests;
...
Additional request monitoring tools;
...