Open Names API

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

The viaEuropa Open Names API provides programmatic search of Ordnance Survey OpenNames locations based on a number of search criteria. Typical usage would be to find all the places that match a search phrase or the coordinates for a particular postcode. Geographical searches are also possible to identify the nearest place to a location coordinate.

API Request Format

Key

All requests must include the 20-character API key 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 key.

All requests are submitted to the following end-point:

https://api.viaeuropa.uk.com/{id}/os/opennames/name?

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

Querying the viaEuropa Open Names API

All queries are executed on OS Open Names as indicated by the /os/opennames/ path of the name end-point.

A number of methods are provided to search for a name.

By Query Term

The most common way of querying the Open Names API is by searching against a particular query term. These are passed to the Open Names API using the 'q' (queryString) parameter:

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

The queryString can be a place name, street name or postcode.

Responses to name 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.

Postcode must be a properly formatted British postcode, white space can be included.

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

By Coordinates

Search based on British National Grid Coordinate is possible using the point parameter:

https://api.viaeuropa.uk.com/{id}/os/opennames/name?point={x},{y}

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:

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

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

If no radius parameter is provided, the results are limited to a search radius of 1000 metres. The maximum radius permitted is 1000 m.

If no radius is provided results are provided up to a maximum distance of 1000m.

Results can also be limited by addition of the maxresults parameter to limit the number of records returned. See below.

By Field Filters

The Open Names API includes the ability to limit the results returned by use of a field filter parameter.

The format of the filter parameter is filter = fieldname comma operator comma value.

fieldname must be a valid field name, matchscore is included.

operator must be one of the following operators:

For example, to find the nearest roads to a particular coordinate the query would be:

https://api.viaeuropa.uk.com/{id}/os/opennames/name?point=400000,300000&filter=type,eq,transportNetwork

Field filters can be combined using the | character. This has the effect of ANDing the queries together:

https://api.viaeuropa.uk.com/{id}/os/opennames/name?point=400000,300000&filter=type,eq,transportNetwork|district_borough,eq,Walsall

This would only return roads in the borough of Walsall.

Modifiers

The results from any query can be modified by the addition of one or several of the modifiers outlined below.

Field Sets

Ordnance Survey OpenNames contains over 30 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 name 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 Open Names 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/opennames/name?q={queryString}&crs=27700

Or to return WGS84 Longitude Latitude degrees:

https://api.viaeuropa.uk.com/{id}/os/opennames/name?q={queryString}&crs=4326

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 Format

All responses to requests to the viaEuropa Open Names API are returned in JSON format.

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 each result in a JSON object called place

"results": [
    {
        "place": {
            "id": "KT113EP",
            "name1": "KT11 3EP",
            "type": "other",
            "local_type": "Postcode",
            "matchscore": 100
        }
    }
]

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 OpenNames fields please refer to the documentation.

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 postcode search, this will be unambiguous and, if found, the matchscore will be 100. However, in cases where an incomplete term is being searched for then the matchscore indicates the similarity between the input query term and the location found.

Metadata

The metadata element contains information about the request:

"metadata": {
    "querytime": 0.03516,
    "vintage": "2018",
    "jobid": 123,
    "count": 1
}