NGD Address API

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

The viaEuropa NGD Address API provides programmatic search of OS National Geographic Database(NGD) Address Theme records, based on a number of search criteria. Typical usage would be to obtain an address using a unique property reference number (UPRN) or get all addresses that use the a particular postcode. Geographical searches are also possible to identify, for example, the nearest address to a location coordinate.

OS NGD Address provides local authority BS7666 addresses, UPRN, coordinates, classification for each address. Addresses at all lifecycle stages are included, as are objects not normally addressable such as car parks. Addresses are updated daily.

Islands Addresses for 'Islands' (Northern Ireland, Isle of Man, Channel Islands) are also available within NGD Address API. However, these data are not covered by all commercial license agreements and may not be available within your implemetation of the viaEuropa API. If you require access to 'Islands' data and find it is not being returned from this API please contact us to discuss having this data added to your license.

API Request Format

End Point

The base end point for NGD Address API is : https://api.viaeuropa.uk.com/{id}/os/ngd2/address?

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:

https://api.viaeuropa.uk.com/{id}/os/ngd2/address?

Results are returned as JSON (default), GeoJson or XML. See API Response Format below for full details.

Querying the viaEuropa NGD Address API

All queries are executed on OS NGD Address Schema 2 as indicated by the /os/ngd2/ path of the address end-point. Any updates to the schema will be released on new end-points matching the schema number.

A number of methods are provided to query an address. Select one of the parameters below to use in a request.

By Unique Property Reference Number

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

https://api.viaeuropa.uk.com/{id}/os/ngd2/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 sorted by name and number :

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

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

By Address Match

Address matching is a means of obtaining an official or clean address(es) from free text input.

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

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

The API will return the best match or matches for the free text provided. The more fields that can be provided in the 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 inclued 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 the full address of the response. A perfect match is 100. Results are ordered by matchscore in descending order to return the best matches first. If a single match is returned then a higher confidence can be given to the returned address.

Partial or ambiguous addresses can be submitted, but will return multiple results. For example q=starbucks+bath will return the four Starbucks with Bath in the address. In the same manner q=high+street+cobham will return all the addresses containing that combination of terms. This may be useful in some scenarios.

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:

https://api.viaeuropa.uk.com/{id}/os/ngd2/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 1,300,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 distance by the addition of a radius parameter:

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

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

Note 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 to the nearest n addresses by addition of the maxresults parameter. See below.

Bounding Box

Search is also possible based on locations falling within a bounding box using the bbox parameter:

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

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 1,300,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 1,300,000 meters.

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:

NGD address also includes an alternate language fulladdress field that provides the address in Welsh and Scottish Gaelic where appropriate. This field can be returned by using the alternative fieldset. If no alternative to English is available this field is blank.

Country Restriction

To limit the results to those only falling within specfic countries, or principalities, a countries parameter can be added to the request. This restricts results to those that fall within that country. Multiple Country codes should be given as a case insensitve comma separated list.

https://api.viaeuropa.uk.com/{id}/os/ngd2/address?bbox={xmin},{ymin},{xmax},{ymax}&countries=eng,wal

Include

OS NGD Address data includes addresses at all stages of their lifecycle. Addresses are included in NGD from the moment they are registered with the local authority. These may be prior to the address being assigned a full postal address, in that situation they are referred to as pre-build and given a preliminary address. Addresses at the end of their lifecycle that have been removed from the full postal register as a result of demolition or renovation are described as historic. By default just the currently built addresses are returned by the API. If pre-build, historic and non-addressible objects are wanted in the results set then the include parameter should be added to the request. This parameter should be formed of a case insensitve comma separated list of three letter codes representing the data as described below.

Note If just one include code is provided then just results of that type will be returned.

https://api.viaeuropa.uk.com/{id}/os/ngd2/address?postcode={postcode}&include=gbb,gbp,gbh

Coordinate Reference Systems

Every address contains a geographic location measured in three 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:

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

Or to return WGS84 Longitude Latitude degrees:

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

API Response

API Response Format

All responses to requests to the viaEuropa NGD Address API are returned in JSON (default), GeoJSON or XML format. The coordinates are returned in EPSG:4326 (WGS84) when the format is GeoJson.

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

https://api.viaeuropa.uk.com/{id}/os/ngd2/address?uprn={uprn}&format=geojson

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": 10033332750,
                "fulladdress": "Europa Technologies Ltd, Suite G3 And G4, Coveham House, Downside Bridge Road, Cobham KT11 3EP",
                "matchscore": 100
            }
        ]
    }

XML

<results>
  <address>
    <uprn>10033332750</uprn>
    <fulladdress>Europa Technologies Ltd, Suite G3 And G4, Coveham House, Downside Bridge Road, Cobham KT11 3EP</fulladdress>
    <matchscore>100</matchscore>
  </address>
</results>

GeoJson

{
    "type": "FeatureCollection",
    "name": "NGD addresses",
    "crs": {
        "type": "name",
        "properties": {
            "name": "urn:ogc:def:crs:EPSG::4326"
        }
    },
    "features": [
        {
            "type": "Feature",
            "id": 10033332750,
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.4122584,
                    51.3292373
                ]
            },
            "properties": {
                "uprn": 10033332750,
                "matchscore": 100,
                "fulladdress": "EUROPA TECHNOLOGIES LTD, SUITE G4 AND H, COVEHAM HOUSE, DOWNSIDE BRIDGE ROAD, COBHAM, KT11 3EP"
            }
        }
    ]
}

Note The above response contains the default 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 NGD Address fields please refer to the documentation.

Metadata

The metadata element contains information about the request and results returned:

JSON

"metadata": {
    "querytime": 0.04819,
    "count": 1,
    "maxResults": 1000,
    "status": "OK"
}

XML

<metadata>
    <querytime>0.04819</querytime>
    <count>1</count>
    <maxResults>1000</maxResults>
    <status>OK</status>
</metadata>