AddressBase Premium API

PSGA Scotland members: You may replace references on this page to the domain api.viaeuropa.uk.com with api.publicsectormapping.gov.scot

The viaEuropa AddressBase Premium API provides programmatic search of Ordnance Survey AddressBase Premium records based on a number of search criteria. Typical usage would be to obtain an address using just a unique property reference number (UPRN) or get all the addresses that use the same postcode. Geographical searches are also possible to identify, for example, the nearest address to a location coordinate.

AddressBase data is available as two products: AddressBase Plus and AddressBase Premium. 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.

AddressBase Premium covers addresses in England, Wales and Scotland only. An extension product, AddressBase Premium Islands adds addresses for Northern Ireland, Isle of Man and Channel Islands (Jersey & Guernsey). viaEuropa API end points are available for AddressBase Premium and AddressBase Premium plus AddressBase Premium Islands. Chose the end point which meets the geographic coverage requirement of your application.

AddressBase Premium provides pre-build addresses, historic addresses, alternative addresses, OS Mastermap Topography and Integrated Transport Network Layer 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 AddressBase Premium end-points available. They share all the options and modifiers listed below and only differ in their geographic coverage.

AddressBase Premium (Great Britain only):
https://api.viaeuropa.uk.com/{id}/os/abpr/address?

AddressBase Premium + AddressBase Premium Islands (Great Britain, Northern Ireland, Isle of Man & Channel Islands):
https://api.viaeuropa.uk.com/{id}/os/abpri/address?

The example requests below are given for both end points.

ID

All requests must include the 20-character API ID 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: xxxxx-xxxxx-xxxxx-xxxxx

In all the following example requests you should substitute {id} with your own ID.

All requests are submitted to one of the following end-points:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?

Results are returned as JSON or XML. See API Response Format below for full details.

By Unique Property Reference Number

Querying the viaEuropa AddressBase Premium API by UPRN, if known, is the simplest way to return an address and can be submitted in the following format:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?uprn={uprn}

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?uprn={uprn}

Where UPRN is an integer.

By Postcode

Querying the API by Postcode returns all the addresses that fall within that postcode:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?postcode={postcode}

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?postcode={postcode}

Postcodes must be a properly formatted Royal Mail postcode, but a space in the middle is optional.

Postcodes in Northern Ireland (BT), Isle of Man (IM) and Jersety (JE) and Guernsey (GE) are only returned from the AddressBase Premium Islands end point.

By Address Match

Address matching is a means of obtaining an official or cleansed address from partial or badly formed input.

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?q={queryString}

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?q={queryString}

Matching against poorly formed, or partial addresses is possible, but results are not guaranteed and false matches possible. The inclusion of a postcode or partial postcode will increase the likelihood of a good match.

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. Results are ordered by matchscore in descending order to return the best matches first.

By Coordinates

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:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?point={x},{y}

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?point={x},{y}

Results from a point-based search are ordered by distance in meters with the distance returned in the distance_m parameter.

Results can be limited by the addition of a radius parameter:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?point={x},{y}&radius=100

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?point={x},{y}&radius=100

This only returns addresses that fall within 100 meters of the coordinates provided.

If no radius parameter is provided then results are limited to a search radius of 1000 meters. 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:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?bbox={xmin},{ymin},{xmax},{ymax},{crs}

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?bbox={xmin},{ymin},{xmax},{ymax},{crs}

Note 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 Sets

Ordnance Survey AddressBase contains many fields of information. To make the response more manageable fields have been grouped into subsets which can be invoked using the fieldset modifier. For example:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?uprn={uprn}&fieldset=all

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?uprn={uprn}&fieldset=all

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 Type

There are two types of address contained in AddressBase Premium:

• Delivery Point Address (DPA)
• Land and Property Identifier (LPI) - the Geographic address

The Delivery Point Address (DPA) is 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.

Geographic Addresses (LPI) are maintained by 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.

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:

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:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?uprn={uprn}&crs=27700

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?uprn={uprn}&crs=27700

Or to return WGS84 Longitude Latitude degrees:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?uprn={uprn}&crs=4326

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?uprn={uprn}&crs=4326

Other Modifiers

There are other modifiers that can be added to requests in order to alter the content of the response.

API Response

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:

AddressBase Premium:
https://api.viaeuropa.uk.com/{id}/os/abpr/address?uprn={uprn}&format=xml

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpri/address?uprn={uprn}&format=xml

API Response 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

UPRN is the addresses Unique Property Reference Number.

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

Matchscore is 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"
}

XML

<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>