OS AddressBase Premium 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 Premium 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.
When compared with OS AddressBase Plus, OS AddressBase Premium is a slightly more extensive data set as it includes pre-build addresses, historic addresses and alternative addresses. Further information on how AddressBase products compare.
OS AddressBase Premium covers addresses in England, Wales and Scotland only. An extension product, OS AddressBase Premium Islands adds addresses for Northern Ireland, Isle of Man and Channel Islands (Jersey & Guernsey). viaEuropa API end points are available for OS AddressBase Premium, optionally with OS AddressBase Premium Islands. Choose the end point which meets the geographic coverage requirements of your application.
OS AddressBase Premium provides pre-build addresses, historic addresses, alternative addresses, OS MasterMap Topography TOIDs and the associated alternative record, objects without postal addresses, addresses with multiple occupants, local authority BS7666 addresses, Royal Mail postal addresses, where matched to a UPRN, coordinates for each address.
API Request Format
End Points
There are two OS AddressBase Premium 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 Premium:
OS AddressBase Premium with Islands:
The example requests below are given for OS AddressBase Premium (England, Wales and Scotland). If you want to add results from Islands (Northern Ireland, Isle of Man and Channel Islands), then substitute abpr for abpri.
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 Premium:
OS AddressBase Premium 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 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 Premium:
OS AddressBase Premium 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 Premium:
OS AddressBase Premium 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 Premium:
OS AddressBase Premium 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 Premium:
OS AddressBase Premium 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 Premium:
OS AddressBase Premium 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 Premium:
OS AddressBase Premium 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 Premium 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 |
Address Status
AddressBase Premium contains alternative and full lifecycle addresses. To limit the type of addresses returned to those that match a particular lifecycle status, an addressstatus filter is provided. Single or multiple values may be provided as long as they are comma separated e.g. addressstatus=1,6. If no address status is provide then only approved (1) addresses are returned.
| Address Status | Description |
|---|---|
| 1 | Approved (default) |
| 3 | Alternative |
| 6 | Provisional |
| 8 | Historical |
Address Type
There are two types of address contained in AddressBase Premium:
- Delivery Point Address (DPA)
- Land and Property Identifier (LPI)
DPA addresses are sourced from Royal Mail’s PAF (Postcode Address File) which is a non-geocoded list of addresses. These addresses are used primarily as a ‘mailing list’ for postal purposes.
LPI addresses are sourced from contributing Local Authorities. The structure of a geographic address is based on the British Standard BS7666. These addresses are used to provide an accurate geographic locator for an object to aid, for example, service delivery, asset management, or command and control operations. They also represent the legal form of addresses as created under street naming and numbering legislation.
Use the modifier addresstype=dpa or addresstype=lpi to return results from just one of these sources. When used in combination with fieldset=postal the fields returned will be restricted to just the postal fields from the selected address type.
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 Premium:
OS AddressBase Premium with Islands:
Or to return Latitude/Longitude coordinates in decimal degrees:
OS AddressBase Premium:
OS AddressBase Premium 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.
GeoSON
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 WGS84 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 Premium:
OS AddressBase Premium 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 Premium fields please refer to the 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. The source for this field will be the delivery point address (dpa), often also knows as PAF, or the address created by the appropriate local authority (lpi). The lpi address is used by default, but dpa can be specified using the addresstype filter.
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": {
"query": "query text as submitted",
"querytime": 0.04819,
"vintage": 62,
"jobid": "123",
"count": 1,
"addresstype": "lpi",
"status": "OK"
}
<metadata>
<query>query text as submitted</query>
<querytime>0.06892</querytime>
<vintage>62</vintage>
<jobid>123<jobid/>
<count>1</count>
<addresstype>lpi</addressType>
<status>OK</status>
</metadata>
| Element | Description |
|---|---|
| query | The query used to select addresses |
| querytime | The time in seconds taken to run the database query |
| vintage | The epoch of OS AddressBase Premium in production |
| jobid | If a jobid parameter is passed in the request, it is returned here |
| count | Number of results returned |
| addresstype | The source of the address provided, DPA or LPI |
| status | Status of the response |