National Address Search

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.

The 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 refreshed 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.

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",
        "bs7666_primary_classification_description", 
        "bs7666_primary_classification_code", 
        "bs7666_secondary_classification_description", 
        "bs7666_secondary_classification_code", 
        "bs7666_tertiary_classification_description", 
        "bs7666_tertiary_classification_code", 
        "bs7666_quaternary_classification_description", 
        "bs7666_quaternary_classification_code", 
        "local_custodian_code",
        "authority"],
       "data": [
        
                [
                "10033529251", "8401123", "Bay Oil Supply Co Ltd, Baker Street, London, <b>NW1 6XE</b>", "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", "Commercial", "C", "", "", "", "", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619968", "8401123", "Sweet & Liberty, 215 Baker Street, London, <b>NW1 6XE</b>", "Property", "527870.4", "182081.17", "15%", "Sweet & Liberty, 215 Baker Street, London, NW1 6XE", "100", "SWEET & LIBERTY", "", "", "", "", "", "", "215", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "", "215", "Commercial", "C", "Retail", "R", "Restaurant / Cafeteria", "07", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619968", "8401123", "Sweet & Liberty, 215 Baker Street, London, <b>NW1 6XE</b>", "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"
				]
				, 
                [
                "10033619968", "8401123", "Sweet & Liberty, 215 Baker Street, London, <b>NW1 6XE</b>", "Property", "527870.4", "182081.17", "15%", "Sweet & Liberty, 215 Baker Street, London, NW1 6XE", "100", "SWEET & LIBERTY", "", "", "", "", "", "", "215", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "", "215", "Commercial", "C", "Storage Land", "S", "", "", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619969", "8401123", "219 Baker Street, London, <b>NW1 6XE</b>", "Property", "527868.08", "182090.78", "23%", "219 Baker Street, London, NW1 6XE", "100", "", "", "", "", "", "", "", "219", "", "", "", "BAKER STREET", "", "LONDON", "", "NW1 6XE", "", "219", "Parent Shell", "P", "Property Shell", "P", "", "", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619971", "8401123", "Flat 1, 219 Baker Street, London, <b>NW1 6XE</b>", "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", "Residential", "R", "Dwelling", "D", "Self Contained Flat (Includes Maisonette / Apartment)", "06", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619980", "8401123", "Flat 10, 219 Baker Street, London, <b>NW1 6XE</b>", "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", "Residential", "R", "Dwelling", "D", "Self Contained Flat (Includes Maisonette / Apartment)", "06", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619981", "8401123", "Flat 11, 219 Baker Street, London, <b>NW1 6XE</b>", "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", "Residential", "R", "Dwelling", "D", "Self Contained Flat (Includes Maisonette / Apartment)", "06", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619982", "8401123", "Flat 12, 219 Baker Street, London, <b>NW1 6XE</b>", "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", "Residential", "R", "Dwelling", "D", "Self Contained Flat (Includes Maisonette / Apartment)", "06", "", "", "5990", "City Of Westminster"
				]
				, 
                [
                "10033619983", "8401123", "Flat 13, 219 Baker Street, London, <b>NW1 6XE</b>", "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", "Residential", "R", "Dwelling", "D", "Self Contained Flat (Includes Maisonette / Apartment)", "06", "", "", "5990", "City Of Westminster"
				]
				
        ],
        "total": 0        
    }

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` `bs7666_primary_classification_description` `bs7666_primary_classification_code` `bs7666_secondary_classification_description` `bs7666_secondary_classification_code` `bs7666_tertiary_classification_description` `bs7666_tertiary_classification_code` `bs7666_quaternary_classification_description` `bs7666_quaternary_classification_code` `(non-bs7666) local_custodian_code` `(non-bs7666) authority`

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.

Licensing

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;
Refinements to the search algorithm.