OS NGD Address 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 National Geographic Database (NGD) Address Theme using various search criteria. Typical usage would be to obtain an address using a Unique Property Reference Number (UPRN) or get all addresses that use 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 coverage of Northern Ireland, Isle of Man and the Channel Islands, is also available within this API. While covered by the PSGA, this extension is not covered by all commercial license agreements and may not be available to you using the viaEuropa API. If you are a commercial organisation and require access to Islands addresses, please contact Support for assistance.
API Request Format
End Points
The base end point for NGD Address API is:
For customers with GB-only access to NGD Address, the following base end point is provided:
viaEuropa 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:
In all the following example requests you should substitute {id} with your own ID.
All requests are submitted to the following end-point:
Results are returned as JSON (default), GeoJSON or XML. See API Response Format below for full details.
Making Queries
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 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:
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 :
where:
{id} is your viaEuropa ID
{postcode} is a correctly formatted British 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.
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 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 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 (at time of writing) 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 where a fair location description is available but the full address is not known.
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:
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 1,300,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 distance by the addition of a radius parameter:
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 metres. 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:
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 1,300,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 1,300,000 metres.
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 Set
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:
| fieldset | response |
|---|---|
| summary | UPRN, fulladdress, matchscore fields. Default |
| alternative | UPRN, alternative language fulladdress, matchscore fields. |
| postal | Returns all postal address fields as separate fields |
| all | Returns all OS fields provided in NGD Address |
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 Filter
To limit the results to those only falling within specific 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 insensitive, comma separated, list.
| Country | countries |
|---|---|
| England | eng |
| Scotland | sco |
| Wales | wal |
| Northern Ireland | nir |
| Isle of Man | iom |
| Guernsey | gue |
| Jersey | jer |
| All | all (default) |
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-addressable 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 insensitive comma separated list of three letter codes representing the data as described below.
| Data source | include |
|---|---|
| Great Britain - Built | gbb (default) |
| Great Britain - Prebuild | gbp |
| Great Britian - Historic | gbh |
| Great Britian - Non-addressible | gbn |
| Islands - Built | isb (default) |
| Islands - Prebuild | isp |
| Islands - Historic | ish |
| Islands - Non-addressible | isn |
| All | all |
Results will only include results from the data sources specified.
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:
| EPSG Code | Description |
|---|---|
| 27700 | British National Grid. XY coordinates in metres |
| 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:
Or to return Latitude/Longitude coordinates in decimal degrees:
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.
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"
}
}
]
}
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 NGD Address fields please refer to the documentation.
Metadata
The metadata element contains information about the request and results returned: JSON
XML<metadata>
<querytime>0.04819</querytime>
<count>1</count>
<maxResults>1000</maxResults>
<status>OK</status>
</metadata>
| Element | Description |
|---|---|
| querytime | The time in seconds taken to run the database query |
| count | Number of results returned |
| maxResults | Maximum number of results returned |
| status | Status of the response, should be 'OK' |