Technical specification

This technical specification explains the content of the OS Names API and the methods you can use to call it.

This technical specification extends the Infrastructure for Spatial Information in the European Community (INSPIRE) Geographical Names theme to ensure compliance with European open data initiatives.

If you are not familiar with the OS Names API please read the overview documentation before proceeding.

Core concepts

This specification does not cover core concepts that apply to all Ordnance Survey APIs.

Please read the following pages to learn more about OS API core concepts:

• Authentication

• Error codes

• Rate-limiting policy

API reference

The OS Names API is an API, which returns queries to the service in either XML or JSON. The service offers two resources:

• Find a string-based lookup service.

• Nearest uses a pair of BNG coordinates to return the nearest features.

A free string text search, intended to be an ambiguous/fuzzy search.

GEThttps://api.os.uk/search/names/v1/find

Authorization

api-key

Query parameters

Response

200

Retrieves addresses based on a free text search.

Body

application/jsonapplication/xml

headerHeader (object)

resultsarray of GazetteerEntry (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/names/v1/find?query=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "format": "text",
    "maxresults": 0,
    "offset": 0,
    "totalresults": 0
  },
  "results": [
    {
      "ID": 0,
      "NAMES_URI": "text",
      "NAME1": "text",
      "TYPE": "text",
      "LOCAL_TYPE": "text",
      "GEOMETRY_X": 0,
      "GEOMETRY_Y": 0,
      "MOST_DETAIL_VIEW_RES": 0,
      "LEAST_DETAIL_VIEW_RES": 0,
      "MBR_XMIN": 0,
      "MBR_YMIN": 0,
      "MBR_XMAX": 0,
      "MBR_YMAX": 0,
      "POSTCODE_DISTRICT": "text",
      "POSTCODE_DISTRICT_URI": "text",
      "POPULATED_PLACE": "text",
      "POPULATED_PLACE_URI": "text",
      "POPULATED_PLACE_TYPE": "text",
      "COUNTY_UNITARY": "text",
      "COUNTY_UNITARY_URI": "text",
      "COUNTY_UNITARY_TYPE": "text",
      "REGION": "text",
      "REGION_URI": "text",
      "COUNTRY": "text",
      "COUNTRY_URI": "text"
    }
  ]
}

Find the features closest to a given point

GEThttps://api.os.uk/search/names/v1/nearest

Authorization

api-key

Query parameters

Response

200

Retrieves addresses based on a free text search.

Body

application/jsonapplication/xml

headerHeader (object)

resultsarray of GazetteerEntry (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/names/v1/nearest?point=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "format": "text",
    "maxresults": 0,
    "offset": 0,
    "totalresults": 0
  },
  "results": [
    {
      "ID": 0,
      "NAMES_URI": "text",
      "NAME1": "text",
      "TYPE": "text",
      "LOCAL_TYPE": "text",
      "GEOMETRY_X": 0,
      "GEOMETRY_Y": 0,
      "MOST_DETAIL_VIEW_RES": 0,
      "LEAST_DETAIL_VIEW_RES": 0,
      "MBR_XMIN": 0,
      "MBR_YMIN": 0,
      "MBR_XMAX": 0,
      "MBR_YMAX": 0,
      "POSTCODE_DISTRICT": "text",
      "POSTCODE_DISTRICT_URI": "text",
      "POPULATED_PLACE": "text",
      "POPULATED_PLACE_URI": "text",
      "POPULATED_PLACE_TYPE": "text",
      "COUNTY_UNITARY": "text",
      "COUNTY_UNITARY_URI": "text",
      "COUNTY_UNITARY_TYPE": "text",
      "REGION": "text",
      "REGION_URI": "text",
      "COUNTRY": "text",
      "COUNTRY_URI": "text"
    }
  ]
}