OS AddressBase Plus API
PSGA Scotland members
You may replace references to the domain api.viaeuropa.uk.com with api.publicsectormapping.gov.scot
This viaEuropa API provides programmatic search of OS AddressBase Plus using various search criteria. Typical usage would be to obtain an address using free text search, Unique Property Reference Number (UPRN) or get all addresses that share a single postcode. Geographical searches are also possible to identify, for example, the nearest address to a location coordinate.
OS AddressBase Plus covers addresses in England, Wales and Scotland only. An extension product, OS AddressBase Plus Islands adds addresses for Northern Ireland, Isle of Man and Channel Islands (Jersey & Guernsey). viaEuropa API end points are available for OS AddressBase Plus, optionally with OS AddressBase Plus Islands. Choose the end point which meets the geographic coverage requirements of your application.
OS AddressBase Plus provides Local authority BS7666 addresses, Royal Mail postal addresses, UPRN, coordinates for each address, objects without postal addresses, addresses with multiple occupants and OS MasterMap Topography Layer TOIDs.
API Request Format
End Points
There are two OS AddressBase Plus end-points available. Both end points share all options and modifiers listed below, the only difference between the two is their geographic coverage:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
The example requests below are given for OS AddressBase Plus (England, Wales and Scotland). If you want to add results from Islands (Northern Ireland, Isle of Man and Channel Islands), then substitute abpl for abpli.
viaEuropa ID
All requests must include a viaEuropa provided by Europa Technologies as part of the URI.
This will always be in the format of four blocks of five uppercase alpha-numeric characters, each block separated by a dash:
In all the following example requests you should substitute {id} with your own ID.
All requests are submitted to the following end-point:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
Results are returned as JSON or XML. See API Response Format below for full details.
Making Queries
A number of methods are provided to query an addresses.
By UPRN
Querying the API by UPRN, if known, is the simplest way to return an address. The request can be submitted in the following format:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
where:
{id} is your viaEuropa ID
{uprn} is a valid Unique Property Reference Number (UPRN)
By Postcode
Querying the API by postcode returns all the addresses that match that postcode:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
where:
{id} is your viaEuropa ID
{postcode} is a correctly formatted Royal Mail postcode.
By Address Text
Querying the API by free text is possible using the following request format. This can be useful for incomplete or badly formed input.
OS AddressBase Plus:
OS AddressBase Plus with Islands:
where:
{id} is your viaEuropa ID
{q} is a free text address
The API will return the best match or matches for the free text provided. The more address elements that can be provided as free text, the higher the likelihood of a good match. Matching against poorly formed, or partial addresses is possible, but results are not guaranteed and false matches are always possible. The supplied address text should be in standard address format and included a postcode or partial postcode at the end of the string if possible.
Responses to address match queries always include a result parameter called matchscore. This indicates the character by character similarity of the match between the query term and each response. A perfect match is 100.
Tip
This query type returns just one result by default. If you would like multiple results, set maxresults=1000. Results are ordered by matchscore in descending order to return the best matches first.
By Geometry
Geographic searches for addresses can be executed by passing a point or bounding box coordinates.
Point
Search based on proximity to a British National Grid coordinate is possible using the point parameter:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
where:
{id} is your viaEuropa ID
{x} is a valid Easting coordinate in British National Grid. Range 0 to 700,000 metres.
{y} is a valid Northing coordinate in British National Grid. Range 0 to 700,000 metres.
Results from a point-based search are ordered by distance in metres with the distance returned in the distance_m parameter.
Results can be limited by the addition of a radius parameter:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
where:
{radius} is a search radius in metres.
If no radius parameter is provided then results are limited to a search radius of 1000 metres. The maximum radius permitted is 1000 m.
Results can also be limited by addition of the maxresults parameter to limit the number of records returned. See below.
Bounding Box
Search is also possible based on locations falling within a bounding box using the bbox parameter:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
where:
{id} is your viaEuropa ID
{xmin} is a valid minimum Easting coordinate in British National Grid. Range 0 to 700,000 metres.
{ymin} is a valid minimum Northing coordinate in British National Grid. Range 0 to 700,000 metres.
{xmax} is a valid maximum Easting coordinate in British National Grid. Range 0 to 700,000 metres.
{ymax} is a valid maximum Northing coordinate in British National Grid. Range 0 to 700,000 metres.
{crs} is an EPSG code for coordinates.
Warning
A maximum of 1000 results will be returned if the bounding rectangle is large.
Modifiers
The results from any query can be modified by the addition of one or several of the modifiers below.
Field Set
OS AddressBase Plus contains over 80 fields of information. To make the response more manageable fields have been grouped into subsets which can be invoked using the fieldset parameter:
| fieldset | response |
|---|---|
| summary | UPRN and summary_address fields. Default |
| postal | Returns all address fields as separate fields |
| essential | Returns all address fields, summary_address and OS MasterMap Topography TOIDs |
| all | Returns all OS fields provided in AddressBase |
Location
Coordinate Reference Systems
Every address contains a geographic location measured in four different coordinate reference systems (CRS), the most familiar of which will be British National Grid. But others are provided to facilitate use of the API in web mapping and other similar geo-spatial applications. CRS are often referred to using an EPSG code in addition to their descriptive name.
The EPSG codes and descriptions for the coordinates provided in the viaEuropa Address API are:
| EPSG Code | Description |
|---|---|
| 27700 | British National Grid. XY coordinates in metres |
| 4258 | European Terrestrial Reference System 1989. Latitude/Longitude Coordinates in decimal degrees |
| 3857 | Pseudo-Mercator / Spherical Mercator. XY coordinates in metres |
| 4326 | World Geodetic System 1984. Latitude/Longitude Coordinates in decimal degrees |
In order to return coordinates in the response a CRS parameter needs to be provided in the form of an EPSG code.
For example, to obtain X and Y coordinates in British National Grid a request should be made in the format:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
Or to return Latitude/Longitude coordinates in decimal degrees:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
Location Formats
By default location coordinates, when requested, are returned as standard number fields.
JSON
It is possible to return the coordinate pairs as a JSON array by the addition of a locformat=json parameter.
GeoJSON
It is possible to return the coordinate pairs as a GeoJSON element by the addition of a locformat=geojson parameter but this is only available when the crs is set to 4326 as GeoJSON only supports WGS-84 coordinates.
Other Modifiers
There are other modifiers that can be added to requests in order to alter the content of the response.
| Field | Description | Type |
|---|---|---|
| maxresults | Add a limit to the number of results returned. Default is 1 for address search and 1000 for all other types of search |
Integer |
| jobid | A user code passed in the request that is returned in the metadata. | AlphaNumeric |
| format | The response format. json(default) or xml. | AlphaNumeric |
API Response
Format
All responses to requests to the viaEuropa Address API are returned in JSON (default) or XML format.
To obtain the API response in XML format add the modifier format=xml to the request:
OS AddressBase Plus:
OS AddressBase Plus with Islands:
Structure
There are two root elements in the response:
- results contains the results of the query
- metadata contains information about the request
Results
The results element contains the results of the query in an array called Address
JSON
"results": [
{
"address": [
{
"uprn": 10033322837,
"summary_address": "Europa Technologies Ltd, Suite G3 And G4, Coveham House, Downside Bridge Road, Cobham KT11 3EP",
"matchscore": 100
}
]
}
XML
<results>
<address>
<uprn>10033322837</uprn>
<summary_address>Europa Technologies Ltd, Suite G3 And G4, Coveham House, Downside Bridge Road, Cobham KT11 3EP</summary_address>
<matchscore>100</matchscore>
</address>
</results>
The above response contains the minimal field set that is returned to any request. Other fields may be added according to the fieldset parameter as described earlier.
For more information about the OS AddressBase Plus fields please refer to the product documentation.
The results array contains an address array with all the address objects that match the request parameters.
uprn - The Unique Property Reference Number (UPRN).
summary_address - The summary address is a single field that logically concatenates the separate postal fields to provide a more human readable address.
matchscore - An integer from 0 to 100 that indicates the quality of the match between the input parameters and the result(s) found. In many cases, such as a UPRN search, this will be unambiguous and the matchscore will be 100. However, in cases where an incomplete address is being searched for then the matchscore indicates the similarity between the input query term and the address found.
Metadata
The metadata element contains information about the request:
JSON
"metadata": {
"querytime": 0.04819,
"vintage": 62,
"jobid": 123,
"count": 1,
"maxResults": 1000,
"status": "OK"
}
<metadata>
<querytime>0.06892</querytime>
<vintage>62</vintage>
<jobid>123<jobid/>
<count>1</count>
<maxResults>1000</maxResults>
<status>OK</status>
</metadata>
| Element | Description |
|---|---|
| querytime | The time in seconds taken to run the database query |
| vintage | The epoch of OS AddressBase Plus in production |
| jobid | If a jobid parameter is passed in the request, it is returned here |
| count | Number of results returned |
| maxResults | Maximum number of results returned |
| status | Status of the response |