AddressBase Plus API

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

The viaEuropa AddressBase Plus API provides programmatic search of Ordnance Survey AddressBase Plus 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 Plus covers addresses in England, Wales and Scotland only. An extension product, AddressBase Plus Islands adds addresses for Northern Ireland, Isle of Man and Channel Islands (Jersey & Guernsey). viaEuropa API end points are available for AddressBase Plus and AddressBase Plus plus AddressBase Plus Islands. Chose the end point which meets the geographic coverage requirement of your application.

Ordnance Survey AddressBase Plus provides Local authority BS7666 addresses, Royal Mail postal addresses, UPRN, coordinates for each address, objects without postal addresses, addresses with multiple occupants, OS MasterMap Topography Layer and Integrated Transport Network TOIDs.

API Request Format

End Points

There are two Address Base Plus end-points available. Both end points share all options and modifiers listed below, the only difference between the two is their Geographic coverage :

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

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

The example requests below are given for Address Base Plus (England, Wales and Scotland). If you want to add results from the 'islands' regions then substitute abpl for abpli

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 the following end-point:

AddressBase Plus:
https://api.viaeuropa.uk.com/{id}/os/abpl/address?

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

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

Querying the viaEuropa AddressBase Plus API

All queries are executed on OS AddressBase Plus as indicated by the /os/abpl/ path of the address end-point.

A number of methods are provided to query an address.

By Unique Property Reference Number

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

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

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

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 fall within that postcode:

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

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

where:
{id} is your viaEuropa ID
{postcode} is a correctly formatted British postcode.

Postcodes in Northern Ireland (BT postcode area) are not supported at this time.

By Address Match

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

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

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

where:
{id} is your viaEuropa ID
{q} is a free text address

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 Plus: https://api.viaeuropa.uk.com/{id}/os/abpl/address?point={x},{y}

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

where:
{id} is your viaEuropa ID
{x} is a valid Easting coordinate in British National Grid. Range 0 to 700,000 meters.
{y} is a valid Northing coordinate in British National Grid. Range 0 to 700,000 meters.

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 Plus: https://api.viaeuropa.uk.com/{id}/os/abpl/address?point={x},{y}&radius={radius}

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

where:
{radius} is a search radius in metres.

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 Plus: https://api.viaeuropa.uk.com/{id}/os/abpl/address?bbox={xmin},{ymin},{xmax},{ymax},{crs}

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

where:
{id} is your viaEuropa ID
{xmin} is a valid minimum Easting coordinate in British National Grid. Range 0 to 700,000 meters.
{ymin} is a valid minimum Northing coordinate in British National Grid. Range 0 to 700,000 meters.
{xmax} is a valid maximum Easting coordinate in British National Grid. Range 0 to 700,000 meters.
{ymax} is a valid maximum Northing coordinate in British National Grid. Range 0 to 700,000 meters.
{crs} is an EPSG code for coordinates.

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

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:

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 Plus: https://api.viaeuropa.uk.com/{id}/os/abpl/address?uprn={uprn}&crs=27700

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

Or to return WGS84 Longitude Latitude degrees:

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

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

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 WGS84 coordinates.

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 Plus: https://api.viaeuropa.uk.com/{id}/os/abpl/address?uprn={uprn}&format=xml

AddressBase Premium + AddressBase Premium Islands:
https://api.viaeuropa.uk.com/{id}/os/abpli/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 Plus 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.

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": {
    "querytime": 0.04819,
    "vintage": 62,
    "jobid": 123,
    "count": 1,
    "maxResults": 1000,
    "status": "OK"
}

XML

<metadata>
    <querytime>0.06892</querytime>
    <vintage>62</vintage>
    <jobid>123<jobid/>
    <count>1</count>
    <maxResults>1000</maxResults>
    <status>OK</status>
</metadata>