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 Address Base Premium data. At present it is provided on a beta service.
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 FIS Print to PDF and WPS service requests.
Request and Response
Requests are made in the following form (for example searching on the postcode NW1 6XE)
https://go.yourcouncil.gov.uk/nlpg?pagesize=10&startnum=1&location=NW1%206XE
(where %20 is the HTML URL encoding of a space).
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).
{
"name": "tempLocSearch",
"columns": [
"UniqueId",
"Parent",
"DisplayName",
"Type",
"X",
"Y",
"Rank",
"Name",
"Zoom",
"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",
"local_custodian_code",
"authority"
],
"data": [
[ "10033529251", "8401123", "Bay Oil Supply Co Ltd, Baker Street, London, NW1 6XE", "Property", "527845", "182149", "15%", "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" ] ,
[ "10033619968", "8401123", "Sweet & Liberty, 215 Baker Street, London, NW1 6XE", "Property", "527870.4", "182081.17", "15%", "Sweet & Liberty, 215 Baker Street, London, NW1 6XE", "100", "SWEET & LIBERTY", "", "", "", "", "", "", "215", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "", "215", "5990", "City of Westminster" ] ,
[ "10033619969", "8401123", "219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "23%", "219 Baker Street, London, NW1 6XE", "100", "", "", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "", "219", "5990", "City of Westminster" ] ,
[ "10033619971", "8401123", "Flat 1, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 1, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 1", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 1", "219", "5990", "City of Westminster" ] ,
[ "10033619980", "8401123", "Flat 10, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 10, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 10", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 10", "219", "5990", "City of Westminster" ] ,
[ "10033619981", "8401123", "Flat 11, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 11, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 11", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 11", "219", "5990", "City of Westminster" ] ,
[ "10033619982", "8401123", "Flat 12, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 12, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 12", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 12", "219", "5990", "City of Westminster" ] ,
[ "10033619983", "8401123", "Flat 13, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 13, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 13", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 13", "219", "5990", "City of Westminster" ] ,
[ "10033619984", "8401123", "Flat 14, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 14, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 14", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 14", "219", "5990", "City of Westminster" ] ,
[ "10033619985", "8401123", "Flat 15, 219 Baker Street, London, NW1 6XE", "Property", "527868.08", "182090.78", "19%", "Flat 15, 219 Baker Street, London, NW1 6XE", "100", "", "FLAT 15", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "FLAT 15", "219", "5990", "City of Westminster" ]
],
"total": 111
}
|
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 | [ "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 | [ "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 | [ "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 | [ "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 | [ "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 | [ "10033619968", "8401123", "Sweet & Liberty, 215 Baker Street, London, NW1 6XE", "Property", "527870.4", "182081.17", "26%", "Sweet & Liberty, 215 Baker Street, London, NW1 6XE", "100", "SWEET & LIBERTY", "", "", "", "", "", "", "215", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "", "215", "5990", "City of Westminster" ] |
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 | [ "5194314", "20400889", "Ted Baker, Unit 13, Kings Cross Railway Station, Euston Road, London, N1C 4QL", "Property", "530270", "183166", "25%", "Ted Baker, Unit 13, Kings Cross Railway Station, Euston Road, London, N1C 4QL", "100", "TED BAKER", "UNIT 13", "", "", "", "", "KINGS CROSS RAILWAY STATION", "", "", "", "", "EUSTON ROAD", "", "LONDON", "", "N1C 4QL", "UNIT 13", "KINGS CROSS RAILWAY STATION", "5210", "Camden" ] ... etc |
Integration and IP Whitelisting
As added security Astun would intend to restrict the above endpoint by IP address and whitelist queries from either (i) the Council network or (ii) the hosted CRM platform. This would depend on the integration implementation - i.e. whether queries are direct from the user's browser (e.g. JavaScript calls direct to our web service), or via the CRM server (proxy). Basic authentication would only be suitable for proxy requests, as credentials should not be embedded in JavaScript code or entered by users. Further discussion is required between Astun and Walsall / CRM provider.
Licensing
The Council is responsible for ensuring that any contractors are fully compliant with OS Licensing arrangements for Address Base and legal obligations from those license 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;
Refinements to the search algorithm.