1. technology and computing
2. software
3. databases

OS OPEN NAMES API
User guide
and
Technical Specification
OS Open Names API
User guide
Contents
Chapter 1
Chapter 2
Preface ................................................................................................................................................... 2
Contact details ....................................................................................................................................... 2
Use of the product ................................................................................................................................. 2
Purpose and disclaimer ......................................................................................................................... 2
Copyright in this guide........................................................................................................................... 2
Data copyright and other intellectual property rights ......................................................................... 3
Trademarks ............................................................................................................................................ 3
Back-up provision of the product ......................................................................................................... 3
Using this guide ..................................................................................................................................... 3
Introduction ................................................................................................................... 4
Overview ................................................................................................................................................ 4
OS Open Names ..................................................................................................................................... 4
Content .................................................................................................................................................. 4
OS Open Names API Products ........................................................................................... 5
Find......................................................................................................................................................... 5
Nearest ................................................................................................................................................... 6
Annexe A Product and service performance report form Ordnance Survey welcomes feedback
from its customers about OS Open Names API. ................................................................................... 7
Introduction ........................................................................................................................................... 9
Purpose of this specification and disclaimer ........................................................................................ 9
Copyright in this specification............................................................................................................... 9
Technical specification
Chapter 1
Chapter 2
Chapter 3
Chapter 4
Overview .......................................................................................................................10
RESTful API........................................................................................................................................... 10
Service Content and Structure ............................................................................................................ 10
URI encoding ........................................................................................................................................ 10
Service Data ..................................................................................................................12
Service metadata ................................................................................................................................. 12
Error Messages ..................................................................................................................................... 12
Find & Nearest resources ................................................................................................15
Find resource ....................................................................................................................................... 15
Parameters........................................................................................................................................... 15
Example requests ................................................................................................................................ 15
Nearest resource .................................................................................................................................. 18
Parameters........................................................................................................................................... 18
Example requests ................................................................................................................................ 18
Output ..........................................................................................................................22
DPA keys ......................................................................................................................................... 22
Stress-testing ....................................................................................................................................... 26
API key security .................................................................................................................................... 26
OS Open Names API – user guide and technical specification © Crown copyright Page 1 of 28
Preface
This user guide (hereafter referred to as the guide) is designed to provide an overview of OS Open Names API. It
gives guidelines and advice on how a customer might derive the maximum benefit from the product and it assumes
a general knowledge of geographic information. If you find an error or omission in this guide, or otherwise wish to
make a comment or suggestion as to how we can improve the guide, please contact us at the address shown below.
Contact details
Our Customer Service Centre will be pleased to deal with your enquiries:
Customer Service Centre
Ordnance Survey
Adanac Drive
SOUTHAMPTON
SO16 0AS
General enquiries (calls charged at local rate): +44 (0)3456 05 05 05
Dedicated Welsh Language HelpLine: 03456 05 05 04
Textphone (deaf and hard of hearing users only please): +44 (0)23 8015 6146
Email: [email protected]
or visit the Ordnance Survey website at: www.ordnancesurvey.co.uk
This document has been screened in accordance with the requirements set out in Ordnance Survey's Equality
scheme. If you have difficulty reading this information in its current format and would like to find out how to access
it in a different format (Braille, large print, computer disk or in another language), please contact us on: +44 (0)3456
05 05 05.
Use of the product
The product is made available to you and your organisation on the terms of the Open Government Licence (OGL) at
www.ordnancesurvey.co.uk/business-and-government.
If there is any inconsistency between the terms of the licence and this guide, the terms of the licence prevail.
Purpose and disclaimer
This guide is provided for guidance only and does not constitute any warranty, representation, undertaking,
commitment or obligation (express or implied) about the product or its suitability for any particular purpose. It is
your responsibility to ensure that this product is suitable for your intended purpose.
Ordnance Survey does not accept any liability (whether for breach of contract, negligence or otherwise) for any loss
or liability you or any third party may suffer in relying on this guide and any guidance, suggestion, advice or
explanation provided in it. Ordnance Survey’s liability to you in relation to the product is limited, as set out in the
OS OpenData Licence.
We may change the information in this guide at any time without notice.
We do not accept responsibility for the content of any third party websites, referenced in, or accessed through, this
guide or through the Ordnance Survey website.
Copyright in this guide
This guide, including its mapping images, is © Crown copyright 2015. All rights reserved.
You may copy or distribute any part of this guide to support the use of OS OpenData, including for your personal
use, use in your organisation or business, or for use with, or incorporation in, your product or application.
OS Open Names API – user guide and technical specification © Crown copyright Page 2 of 28
Data copyright and other intellectual property rights
The Crown (or, where applicable, Ordnance Survey’s suppliers) owns the intellectual property rights in the data
contained in this product. You are free to use the product on the terms of the OS OpenData Licence, but must
acknowledge the source of the data by including the following attribution statement: Contains Ordnance Survey
data © Crown copyright and database right 2015.
Trademarks
Ordnance Survey, the OS Symbol, Code-Point, OSGB36, OS OpenSpace and TOID are registered trademarks and
Boundary-Line, Integrated Transport Network, OS Insight, OS Locator, OS MapFinder and OS OpenData are
trademarks of Ordnance Survey, the national mapping authority of Great Britain.
Ordnance Survey acknowledges that any other trademarks referred to are the property of their respective owners.
Back-up provision of the product
You are advised to copy the supplied data to a back-up medium.
Using this guide
The documentation is supplied in portable document format (PDF) only. Adobe® Reader® software, which enables
you to display this guide and incorporates document search and navigation facilities is available free at
http://get.adobe.com/uk/reader/. Hyperlinks are used to navigate between associated parts of the guide and to
relevant Internet resources by clicking on the blue hyperlinks and the table of contents.
OS Open Names API – user guide and technical specification © Crown copyright Page 3 of 28
Chapter 1
Introduction
OS Open Names API will enable customers to perform internet based search queries against services that use the
OS Open Names dataset and receive back relevant gazetteer information to support their internal and external
applications. The intention is to provide various methods that makes specific tasks easier to accomplish.
Overview
The data found in OS Open Names API is derived from OS Open Names. Through a correctly constructed query, OS
Open Names API can be queried, with either JSON or XML returned, based on the content and structure found
within OS Open Names.
OS Open Names
OS Open Names is a geographic directory that contains basic information about identifiable places (NamedPlace). The
content of the gazetteer shall be divided into topics based on their type and local type classification values.
The primary use of OS Open Names is to provide the location for a named place to support discovery or
identification and visualisation, geocoding, routing and navigation and linking diverse information about a place
(for example, statistics, descriptions).
It is intended that the name of the place will be the key property used for querying. It is also recognised that a place
may have multiple names: an official name, which may be defined in multiple languages (English/Welsh or
English/Gaelic), for example, Cardiff (English) and Caerdydd (Welsh).
Names are not unique so additional location information is provided to allow users to refine their query to select
the Named Place they are interested in. These include: postcode district, populated place, district/borough,
county/unitary authority, European region and country.
The OS Open Names specification will extend the Infrastructure for Spatial Information in the European Community
(INSPIRE) Geographical Names Theme to ensure that it is compliant with European open data initiatives.
Content
OS Open Names will contain the following features;
TYPE
LOCAL_TYPE
populated place
city
populated place
town
populated place
suburban area
populated place
village
populated place
hamlet
populated place
other settlement
transport network
named road
transport network
numbered road
transport network
section of named road
transport network
section of numbered road
other
postcode
OS Open Names API – user guide and technical specification © Crown copyright Page 4 of 28
Chapter 2
OS Open Names API Products
OS Open Names API has two resources available:


Find
Nearest
Important: depending on how the GET requests from the client application are handled, or how auto-complete
libraries are configured, this can result in frequent transactions to the service. If intended, frequent calls can be
made, which could aid the user experience, but please be aware that ultimately it is the developer who is in control
of the frequency to which the service is accessed
Find
The find resource is intended to provide a fast lookup service of the content within OS Open Names API via a text
search. This can be used to search for roads, towns, cities and other locations using word based searches.
For example, if searching for a town, the service will return features of the town such as the name, type, central
location, bounding box coordinates for the area, county unitary and region. The service is intended to be a fuzzy
search and therefore will bring back as many results as can be linked to the search term. Therefore a town search
could also bring back roads and other features that contain the search string.
Figure 1 An example of a settlement name and its attributes
OS Open Names API – user guide and technical specification © Crown copyright Page 5 of 28
Nearest
The nearest resource is intended to allow a search of the OS Open Names API using British National Grid
coordinates, and return the nearest feature. Instead of searching by a feature name, coordinates are given to the
API, and the closest place to that area is returned.
OS Open Names API – user guide and technical specification © Crown copyright Page 6 of 28
Annexe A
Product and service performance report form
Ordnance Survey welcomes feedback from its customers about OS Open Names API.
If you would like to share your thoughts with us, please print a copy of this form and when completed post or fax it
to the address below.
Your name: ..........................................................................................................................................................................
Organisation: .......................................................................................................................................................................
Address: ...............................................................................................................................................................................
..............................................................................................................................................................................................
..............................................................................................................................................................................................
Postcode: .............................................................................................................................................................................
Phone: .................................................................................................................................................................................
Fax: ......................................................................................................................................................................................
Email: ...................................................................................................................................................................................
Quotation or order reference: ............................................................................................................................................
Please record your comments or feedback in the space below. We will acknowledge receipt of your form within
three (3) working days and provide you with a full reply or a status report within 21 working days.
If you are posting this form, please send it to:
OS Open Names API Product Manager, Ordnance Survey, Adanac Drive, SOUTHAMPTON, SO16 0AS.
If you wish to return it by fax, please dial 023 8005 6159.
Any personal information that you supply with this report form will be used by Ordnance Survey only in the
improvement of its products and services. It will not be made available to third parties.
OS Open Names API – user guide and technical specification © Crown copyright Page 7 of 28
OS Open Names API – user guide and technical specification © Crown copyright Page 8 of 28
OS Open Names API
Technical Specification
Introduction
Purpose of this specification and disclaimer
This is the technical specification (hereafter referred to as the specification) applicable to the OS Open
Names API product (hereafter referred to as the product), which is referred to in the Framework Direct
Licence, Specific Use Framework Partner Licence or your other customer contract for the product.
Copyright in this specification
This specification, (including for the avoidance of doubt any mapping images reproduced herein), is ©
Crown copyright 2014. All rights reserved.
Any part of this specification may be copied for use internally in your organisation or business so that you
can use OS Open Names API for the purpose for which it is licensed to your organisation or business (but not
otherwise).
No part of this specification may be reproduced or transmitted in any form or by any means (including
electronically) for commercial exploitation without the prior written consent of Ordnance Survey.
No part of this specification may be copied or incorporated in products, services or publications that you
generate for onward sale, or as free promotional or support materials, without the prior written consent of
Ordnance Survey.
OS Open Names API – user guide and technical specification © Crown copyright Page 9 of 28
Chapter 1
Overview
This section describes how to access the service products, best practices for using it and expected behaviour
of the service. The service products described in this documentation are RESTful API services that enables
users to perform Internet-based search queries against services that use the OS Open Names dataset,
receiving back relevant address information for both internal and external applications. The product is
intended to provide a flexible and uncomplicated method with which to accomplish specific tasks.
The service is intended to be a quick and efficient way to access the information held within the OS Open
Names product, via an HTTPS GET request. When a sufficient request is made to the service, either a JSON
or XML reply will be returned, containing the results of the request.
Where applicable, queries to the service can be made in English, Welsh or Gaelic.
RESTful API
A RESTful API is a service with which users can make different requests can be made to a server and the
resources it hosts, extracting relevant results when applicable. The call is done via a HTTPS request. The
product supports GET requests as well as OPTIONS requests.
Service Content and Structure
To make a request to the service, the query has a specific structure that must be adhered to in order to
receive a reply:
















The service is a collection of RESTful resources that accepts HTTPS requests and return responses
over HTTPS.
The service protocol is HTTPS.
The sub-domain is api.ordnancesurvey.co.uk
The resource collection is opennames.
The version is v1.
The service will respond to GET requests and OPTIONS requests.
Attributes that are null will not be included in response for that record.
The service will support the W3C Cross Origin Resource sharing specification.
All parameters and values shall be accepted in any mix of lower or uppercase character.
The service will accept Resource Names in lowercase.
The format of the response can be specified using the format parameter.
The service will return response in XML and JSON, with the default format being JSON.
The service will include the Content-Type in the HTTP header for all responses.
The service will return data using a Unicode character set (UTF-8) that includes accents.
If no data is found for the customer’s request then an empty list should be returned in the
requested format.
The service shall use the authentication method of API key – the parameter of the API key shall be
key.
URI encoding
Please be aware that when sending a query to the service, if the query contains reserved special characters
please encode the query according to standard percent-encoding procedures for a URI. The list of reserved
characters can be located here:
OS Open Names API – user guide and technical specification © Crown copyright Page 10 of 28
http://tools.ietf.org/html/rfc3986#section-2.2
Examples of URI encoding can be found below.
Javascript URI Encoding
var query = “Southampton”;
var encodeUri = encodeURI(query);
PHP URI Encoding
$query = “Southampton”;
$encodeUri = rawurlencode($query);
OS Open Names API – user guide and technical specification © Crown copyright Page 11 of 28
Chapter 2
Service Data
Service metadata
Each request made contains metadata about the request in the header of the response. This information
includes the URI, the string that was queried, the format requested and other information:
uri (char)
The unique resource identifier
Multiplicity: 1
query (char)
Decoded query string
Multiplicity: 1
format (char)
Requested format
Multiplicity: 1
maxresults (integer)
Maximum number of results requested
Multiplicity: 0..1
offset (integer)
The offset requested
Multiplicity: 0..1
totalresults (integer)
Total number of results found
Multiplicity: 1
bounds (integer)
If bounds are specified, the details of it will be shown here
Multiplicity: 0...1
filter (integer)
If a filter is used, the details of it will be shown here
Multiplicity: 0…1
Error Messages
In addition to the code of the response, the Service shall also provide exception messages to provide more
information to the customer. The Service shall return these messages in text/json or text/xml dependent on
what has been requested. Default is json. Values in italics should be replaced with the relevant variable:
OS Open Names API – user guide and technical specification © Crown copyright Page 12 of 28
If the customer requests an Resource name that does not exist:
{
"error": {
"statuscode": "404",
"message": "Resource test does not exist. Valid resources are find,
nearest."
}
}
Missing mandatory parameter:
{
"error": {
"statuscode": "400",
"message": "No query parameter provided"
}
}
Non-valid value for parameter
{
"error": {
"statuscode": "400",
"message": "test is not a valid value for parameter format. Valid values
are JSON, XML."
}
}
If query contains parameter name that is not valid for that resource:
{
"error": {
"statuscode": "400",
"message": "Parameter test is not a valid parameter for resource nearest.
Valid parameters for requested resource are point, radius, format."
}
}
If the customer request has a negative or zero radius for nearest resource:
{
"error": {
"statuscode": "400",
"message": "Radius must be greater than or equal to 0.01 metres.
Requested Radius was radius."
}
}
If the customer request has a invalid point for nearest resource:
{
"error": {
"statuscode": "400",
"message": "Point must be a comma separated coordinate in British
National Grid projection to 2 decimal places or less. Requested point
was point."
OS Open Names API – user guide and technical specification © Crown copyright Page 13 of 28
}
}
If the customer request has an invalid maxresults:
{
"error": {
"statuscode": "400",
"message": "Maxresults must be between 1 and 100. Requested
maxresults was maxresults."
}
}
HTTP Codes
A table of HTTP codes returned by the service can be found below:
Get
200
304
400
401
404
405
500
503
Description
Request has been successful
Not Modified. In response to a conditional GET request this response indicates that the
underlying data has not changed since the previous request, and cached results may be
re-used.
Bad request. E.g. missing query parameter, malformed syntax
Unauthorized – the client has not provided authentication or incorrect authentication
The server has not found anything matching the Request-URI.
Method not allowed. Request used an unsupported HTTP method, e.g. DELETE or PUT
Generic internal server error
Service unavailable due to overloading or maintenance.
OS Open Names API – user guide and technical specification © Crown copyright Page 14 of 28
Chapter 3
Find & Nearest resources
Find resource
The find resource is a service request based on either a full or partial location, intended to be an ambiguous
search function.
Parameters
query (Mandatory: char)
The free text search parameter.
format (optional: char)
The format the response will be returned in. Default value is JSON.
Valid values: xml, json
maxresults (optional: integer)
The maximum number of results to return. Default is 100.
Valid values: 1–100
offset (optional: integer)
Offset the list of returned by this amount.
bounds (optional: char)
The bounds parameter biases results that intersect with that bounding box so that results are more
relevant to the users location or where they are viewing on a map. Where <BoundingBox> is a BNG
bounding box in the form: XMIN,YMIN,XMAX,YMAX e.g. &bounds=414000,114000,414100,114100.
Value: <BoundingBox>
fq (optional: char)
The filter query parameter only currently supports bounding box filtering and filters out results that do not
intersect the bounding box area. Where <filterName> can only currently be 'BBOX' (case insensitive) and
<filterValue> is a BNG bounding box in the form: XMIN,YMIN,XMAX,YMAX e.g.
&fq=BBOX:414000,114000,414100,114100
Value: <filterName:>:<filterValue>
Example requests
Due to the purposely fuzzy nature of the Find resource, the response outputs have been trimmed to the first
response. The total results found by the search can be noted in the header metadata of the response under
the key of ‘totalresults’, with the returned results under the key ‘maxresults’.
Basic Find query request:
https://api.ordnancesurvey.co.uk/opennames/v1/find?query=southampton&key=[INSERT KEY HERE]
OS Open Names API – user guide and technical specification © Crown copyright Page 15 of 28
API components
Description
https://api.ordnancesurvey.co.uk/opennames/v1/
OS Open Names URL.
find?
Resource being
requested.
query=
Free text search
parameter.
&key=
User API authentication
key
Output:
{
"header" : {
"uri" : "
https://api.ordnancesurvey.co.uk/opennames/v1/find?query=southampton",
"query" : "southampton",
"format" : "JSON",
"maxresults" : 100,
"offset" : 0,
"totalresults" : 4905
},
"results" : [ {
"GAZETTEER_ENTRY" : {
"ID" : "osgb4000000074339476",
"NAMES_URI" :
"http://data.ordnancesurvey.co.uk/id/osgb4000000074339476",
"NAME1" : "Southampton",
"TYPE" : "populatedPlace",
"LOCAL_TYPE" : "City",
"GEOMETRY_X" : 441982.0,
"GEOMETRY_Y" : 111882.0,
"MOST_DETAIL_VIEW_RES" : 73000,
"LEAST_DETAIL_VIEW_RES" : 9000000,
"MBR_XMIN" : 436729.0,
"MBR_YMIN" : 109122.0,
"MBR_XMAX" : 447910.0,
"MBR_YMAX" : 118903.0,
"POSTCODE_DISTRICT" : "SO16",
"POSTCODE_DISTRICT_URI" :
"http://data.ordnancesurvey.co.uk/id/postcodedistrict/SO16",
"COUNTY_UNITARY" : "City of Southampton",
"COUNTY_UNITARY_URI" :
"http://data.ordnancesurvey.co.uk/id/7000000000037256",
"COUNTY_UNITARY_TYPE" :
"http://data.ordnancesurvey.co.uk/ontology/admingeo/UnitaryAuthority",
"REGION" : "South East",
"REGION_URI" :
"http://data.ordnancesurvey.co.uk/id/7000000000041421",
"COUNTRY" : "England",
"COUNTRY_URI" :
"http://data.ordnancesurvey.co.uk/id/country/england",
"SAME_AS_GEONAMES" : "http://sws.geonames.org/2637487",
"MATCH" : 1.0,
"MATCH_DESCRIPTION" : "EXACT"
}
},
OS Open Names API – user guide and technical specification © Crown copyright Page 16 of 28
Find XML query request:
https://api.ordnancesurvey.co.uk/opennames/v1/find?query=southampton&format=XML&key=[INSERT
KEY HERE]
API Components
Description
https://api.ordnancesurvey.co.uk/opennames/v1/find?
OS Open Names URL.
find?
Resource being requested.
format=
Format being requested
&key=
User API authentication key
Output:
<places>
<header>
<uri>
https://api.ordnancesurvey.co.uk/opennames/v1/find?query=southampton&format
=XML
</uri>
<query>southampton</query>
<format>xml</format>
<maxresults>100</maxresults>
<offset>0</offset>
<totalresults>4905</totalresults>
</header>
<results>
<GAZETTEER_ENTRY>
<ID>osgb4000000074339476</ID>
<NAMES_URI>
http://data.ordnancesurvey.co.uk/id/osgb4000000074339476
</NAMES_URI>
<NAME1>Southampton</NAME1>
<TYPE>populatedPlace</TYPE>
<LOCAL_TYPE>City</LOCAL_TYPE>
<GEOMETRY_X>441982.0</GEOMETRY_X>
<GEOMETRY_Y>111882.0</GEOMETRY_Y>
<MOST_DETAIL_VIEW_RES>73000</MOST_DETAIL_VIEW_RES>
<LEAST_DETAIL_VIEW_RES>9000000</LEAST_DETAIL_VIEW_RES>
<MBR_XMIN>436729.0</MBR_XMIN>
<MBR_YMIN>109122.0</MBR_YMIN>
<MBR_XMAX>447910.0</MBR_XMAX>
<MBR_YMAX>118903.0</MBR_YMAX>
<POSTCODE_DISTRICT>SO16</POSTCODE_DISTRICT>
<POSTCODE_DISTRICT_URI>
http://data.ordnancesurvey.co.uk/id/postcodedistrict/SO16
</POSTCODE_DISTRICT_URI>
<COUNTY_UNITARY>City of Southampton</COUNTY_UNITARY>
<COUNTY_UNITARY_URI>
http://data.ordnancesurvey.co.uk/id/7000000000037256
</COUNTY_UNITARY_URI>
<COUNTY_UNITARY_TYPE>
http://data.ordnancesurvey.co.uk/ontology/admingeo/UnitaryAuthority
</COUNTY_UNITARY_TYPE>
<REGION>South East</REGION>
<REGION_URI>
http://data.ordnancesurvey.co.uk/id/7000000000041421
OS Open Names API – user guide and technical specification © Crown copyright Page 17 of 28
</REGION_URI>
<COUNTRY>England</COUNTRY>
<COUNTRY_URI>
http://data.ordnancesurvey.co.uk/id/country/england
</COUNTRY_URI>
<SAME_AS_GEONAMES>http://sws.geonames.org/2637487</SAME_AS_GEONAMES>
<MATCH>1.0</MATCH>
<MATCH_DESCRIPTION>EXACT</MATCH_DESCRIPTION>
</GAZETTEER_ENTRY>
</results>
</places>
Nearest resource
The nearest resource returns the closest address to a given point. The coordinates for the point have to be in
British National Grid (BNG) and to two decimal places or less. A property will only be considered to be
included by the search if the Address Seed is in range of the search, regardless of the property’s physical
boundaries.
Parameters
point (Mandatory: char)
One coordinate set in BNG that specifies the coordinate to find the nearest record to in a straight line. The
precision of the coordinates is to two decimal places (i.e. 1cm accuracy)
radius (optional: float)
The radius in metres to search within. Maximum is 1,000 metres. If above then an error message will be
returned (see below). The precision of the distance is to two decimal places (i.e. 1 cm accuracy). Default
value is 100 metres.
format (optional: char)
The format the response will be returned in. Default value is JSON.
Valid values: xml, json
Example requests
Basic Nearest query request:
https://api.ordnancesurvey.co.uk/opennames/v1/nearest?point=437307,115557&key=[INSERT_KEY_HERE]
API Components
Description
https://api.ordnancesurvey.co.uk/opennames/v1/
OS Open Names URL.
nearest?
Resource being requested.
point=
Point being queried
&key=
User API authentication key
Output:
{
OS Open Names API – user guide and technical specification © Crown copyright Page 18 of 28
"header" : {
"uri" : "
https://api.ordnancesurvey.co.uk/opennames/v1/nearest?point=437307%2C115557
",
"query" : "point=437307,115557 radius=100",
"format" : "JSON",
"maxresults" : 1,
"offset" : 0,
"totalresults" : 1
},
"results" : [ {
"GAZETTEER_ENTRY" : {
"ID" : "SO160AS",
"NAMES_URI" :
"http://data.ordnancesurvey.co.uk/id/postcodeunit/SO160AS",
"NAME1" : "SO16 0AS",
"TYPE" : "other",
"LOCAL_TYPE" : "Postcode",
"GEOMETRY_X" : 437293.0,
"GEOMETRY_Y" : 115515.0,
"MOST_DETAIL_VIEW_RES" : 3500,
"LEAST_DETAIL_VIEW_RES" : 18000,
"POPULATED_PLACE" : "Nursling",
"POPULATED_PLACE_URI" :
"http://data.ordnancesurvey.co.uk/id/4000000074339733",
"POPULATED_PLACE_TYPE" :
"http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#otherSettlemen
t",
"DISTRICT_BOROUGH" : "Test Valley",
"DISTRICT_BOROUGH_URI" :
"http://data.ordnancesurvey.co.uk/id/7000000000043511",
"DISTRICT_BOROUGH_TYPE" :
"http://data.ordnancesurvey.co.uk/ontology/admingeo/District",
"COUNTY_UNITARY" : "Hampshire",
"COUNTY_UNITARY_URI" :
"http://data.ordnancesurvey.co.uk/id/7000000000017765",
"COUNTY_UNITARY_TYPE" :
"http://data.ordnancesurvey.co.uk/ontology/admingeo/County",
"REGION" : "South East",
"REGION_URI" :
"http://data.ordnancesurvey.co.uk/id/7000000000041421",
"COUNTRY" : "England",
"COUNTRY_URI" : "http://data.ordnancesurvey.co.uk/id/country/england"
}
} ]
}
Nearest XML with radius query request:
https://api.ordnancesurvey.co.uk/opennames/v1/nearest?point=528658.0,179429.0&format=XML&key=[INS
ERT_KEY_HERE]
API Components
Description
https://api.ordnancesurvey.co.uk/opennames/v1/
OS Open Names URL.
nearest?
Resource being requested.
point=
Point being queried
OS Open Names API – user guide and technical specification © Crown copyright Page 19 of 28
format=
Format being requested
&key=
User API authentication key
Output:
<places>
<header>
<uri>
https://api.ordnancesurvey.co.uk/opennames/v1/nearest?point=437307%2C115557
&format=XML
</uri>
<query>point=437307,115557 radius=100</query>
<format>xml</format>
<maxresults>1</maxresults>
<offset>0</offset>
<totalresults>1</totalresults>
</header>
<results>
<GAZETTEER_ENTRY>
<ID>SO160AS</ID>
<NAMES_URI>
http://data.ordnancesurvey.co.uk/id/postcodeunit/SO160AS
</NAMES_URI>
<NAME1>SO16 0AS</NAME1>
<TYPE>other</TYPE>
<LOCAL_TYPE>Postcode</LOCAL_TYPE>
<GEOMETRY_X>437293.0</GEOMETRY_X>
<GEOMETRY_Y>115515.0</GEOMETRY_Y>
<MOST_DETAIL_VIEW_RES>3500</MOST_DETAIL_VIEW_RES>
<LEAST_DETAIL_VIEW_RES>18000</LEAST_DETAIL_VIEW_RES>
<POPULATED_PLACE>Nursling</POPULATED_PLACE>
<POPULATED_PLACE_URI>
http://data.ordnancesurvey.co.uk/id/4000000074339733
</POPULATED_PLACE_URI>
<POPULATED_PLACE_TYPE>
http://www.ordnancesurvey.co.uk/xml/codelists/localtype.xml#otherSettlement
</POPULATED_PLACE_TYPE>
<DISTRICT_BOROUGH>Test Valley</DISTRICT_BOROUGH>
<DISTRICT_BOROUGH_URI>
http://data.ordnancesurvey.co.uk/id/7000000000043511
</DISTRICT_BOROUGH_URI>
<DISTRICT_BOROUGH_TYPE>
http://data.ordnancesurvey.co.uk/ontology/admingeo/District
</DISTRICT_BOROUGH_TYPE>
<COUNTY_UNITARY>Hampshire</COUNTY_UNITARY>
<COUNTY_UNITARY_URI>
http://data.ordnancesurvey.co.uk/id/7000000000017765
</COUNTY_UNITARY_URI>
<COUNTY_UNITARY_TYPE>
http://data.ordnancesurvey.co.uk/ontology/admingeo/County
</COUNTY_UNITARY_TYPE>
<REGION>South East</REGION>
<REGION_URI>
http://data.ordnancesurvey.co.uk/id/7000000000041421
</REGION_URI>
<COUNTRY>England</COUNTRY>
<COUNTRY_URI>
http://data.ordnancesurvey.co.uk/id/country/england
OS Open Names API – user guide and technical specification © Crown copyright Page 20 of 28
</COUNTRY_URI>
</GAZETTEER_ENTRY>
</results>
</places>
OS Open Names API – user guide and technical specification © Crown copyright Page 21 of 28
Chapter 4
Output
For the resources listed, if the query returns results, the output will vary depending on the dataset chosen.
The datasets share common keys and also have unique keys specific to that dataset.
ID (Text)
Ordnance Survey unique maintained Topographic Identifier.
Size: 39
Multiplicity:1
NAMES_URI (Text)
INSPIRE identifier for the Named Place which is maintained along with the version number and version
date to reflect the lifecycle of the feature.
Size: 39
Multiplicity:1
NAME1 (Text)
The proper noun that applies to the real world entity. Names that are prefixed by the definite article are
not formatted for alphabetical sorting, that is, ‘The Pennines’ not ‘Pennines, The’.
Size: 80
Multiplicity:1
NAME1_LANG (Text)
The language type is only set where more than one name exists.
Size: 3
Multiplicity:0..1
NAME2 (Text)
The proper noun that applies to the real world entity. Names that are prefixed by the definite article are
not formatted for alphabetical sorting, that is, ‘The Pennines’ not ‘Pennines, The’.
Size: 80
Multiplicity:0..1
NAME2_LANG (Text)
The language type is only set where more than one name exists.
Size: 3
Multiplicity:0..1
TYPE (Text)
The INSPIRE type of named place being represented by the specific feature. See:
http://inspire.ec.europa.eu/codelist/NamedPlaceTypeValue/
Size: 30
Multiplicity:1
LOCAL_TYPE (Text)
The Ordnance Survey classification for the named place being represented by the specific feature.
Size: 30
Multiplicity:1
GEOMETRY_X (Float)
Point geometry in British National Grid. Resolution up to 0.001m.
Size: 7 (1)
Multiplicity:1
GEOMETRY_Y (Float)
OS Open Names API – user guide and technical specification © Crown copyright Page 22 of 28
Point geometry in British National Grid. Resolution up to 0.001m.
Size: 8 (1)
Multiplicity:1
MOST_DETAIL_VIEW_RES (Integer)
The maximum recommended viewing resolution or scale at which the names should no longer be
displayed in a viewing service such as a GIS.
Size: 7
Multiplicity:1
LEAST_DETAIL_VIEW_RES (Integer)
The minimum recommended viewing resolution or scale at which the names should no longer be
displayed in a viewing service such as a GIS.
Size: 7
Multiplicity:1
MBR_XMIN (Float)
Bounding box for roads only. For sections of named and numbered roads, the bounding box should be
created around the road links clipped to be completely inside the settlement.
Size: 7(1)
Multiplicity:0..1
MBR_YMIN (Float)
Bounding box for roads only. For sections of named and numbered roads, the bounding box should be
created around the road links clipped to be completely inside the settlement.
Size: 8 (1)
Multiplicity:0..1
MBR_XMAX (Float)
Bounding box for roads only. For sections of named and numbered roads, the bounding box should be
created around the road links clipped to be completely inside the settlement.
Size: 7 (1)
Multiplicity:0..1
MBR_YMAX (Float)
Bounding box for roads only. For sections of named and numbered roads, the bounding box should be
created around the road links clipped to be completely inside the settlement.
Size: 8 (1)
Multiplicity:0..1
POSTCODE_DISTRICT (Text)
The postcode district, for example, SO15.
Size: 4
Multiplicity:0..1
POSTCODE_DISTRICT_URI (Text)
The Linked Data identifier for Code-Point Open. Linked Data is a useful way of looking at or utilising data
associated with the feature.
Size: 60
Multiplicity:0..1
POPULATED_PLACE (Text)
The name of the settlement that the road or postcode is within to give additional context. Where the
settlement has more than one name, the name is concatenated with a space and a forward slash.
Size: 80
Multiplicity:0..1
POPULATED_PLACE_URI (Text)
OS Open Names API – user guide and technical specification © Crown copyright Page 23 of 28
This is the Linked Data identifier for the settlement. Linked Data is a useful way of looking at or utilising
data associated with the feature.
Size: 60
Multiplicity:0..1
POPULATED_PLACE_TYPE (Text)
URI to the code list which classifies the types of settlement that the feature is within.
Size: 80
Multiplicity:0..1
DISTRICT_BOROUGH (Text)
The name of the District, Metropolitan District or London Borough administrative unit that the geometry
for the feature is within, to give additional context to the location of the feature.
Size: 80
Multiplicity:0..1
DISTRICT_BOROUGH_URI (Text)
The Linked Data reference to the District.
Size: 80
Multiplicity:0..1
DISTRICT_BOROUGH_TYPE (Text)
The URI of the codelist which classifies the type of administrative unit.
Size: 80
Multiplicity:0..1
COUNTY_UNITARY (Text)
The name of the County (non-metropolitan or Metropolitan) or Unitary Authority or Greater London
Authority administrative area that the geometry for feature is within.
Size: 80
Multiplicity:0..1
COUNTY_UNITARY_URI (Text)
The Linked Data reference to the County, Unitary Authority or Greater London Authority.
Size: 80
Multiplicity:0..1
COUNTY_UNITARY_TYPE (Text)
The URI to the codelist which classifies the type of administrative unit.
Size: 80
Multiplicity:0..1
REGION (Text)
The name of the European Region (was Government Office Region) that the geometry for the feature is
within.
Size: 30
Multiplicity:1
REGION_URI (Text)
The Linked Data reference to the European region.
Size: 60
Multiplicity:1
COUNTRY (Text)
The name of the country that the geometry for the feature is within
Size: 30
Multiplicity:1
COUNTRY_URI (Text)
OS Open Names API – user guide and technical specification © Crown copyright Page 24 of 28
The Linked Data reference to the country.
Size: 60
Multiplicity:1
RELATED_SPATIAL_OBJECT (Text)
References the OS MasterMap ITN Layer TOID for Sections of road names and numbers.
Size: 20
Multiplicity:0..1
SAME_AS_GEONAMES (Text)
References Geonames for settlements.
Size: 100
Multiplicity:0..1
SAME_AS_DBPEDIA (Text)
References DBPedia for settlements.
Size: 100
Multiplicity:0..1
OS Open Names API – user guide and technical specification © Crown copyright Page 25 of 28
Annexe A
OS Open Names API usage
Stress-testing
The user is not allowed to stress-test the service at any time. If the user requires to stress-test OS Open
Names API, then please contact Ordnance Survey at least two weeks in advance, who will discuss your
requirements.
API key security
The security and usage of the API key is the responsibility of the developer. If the API key is visible to the
end-user, then adequate procedures should be undertaken to ensure that the key is not used by unintended
parties.
OS Open Names API – user guide and technical specification © Crown copyright Page 26 of 28
Annexe B
Glossary
The purpose of this chapter is to provide a glossary of terms used in the definition of products, services,
licensing and other terms and conditions for OS Open Names API products.
Where terms refer to other terms within the glossary, they are connected by means of hyperlinks to the
relevant entries.
API
Application programming interface.
attribute
Any item of information packaged in an OS Open Names feature. The ID and the geometry of the feature are
both attributes of the feature.
conditional
Dependent upon the type of the field being mandatory or optional for the data to be entered.
contributing authority
A local authority responsible for creating and maintaining an LLPG.
data source
The source of the application cross reference. An external dataset that is linked to or provides a source of ACI.
database
A system intended to organise, store, and retrieve large amounts of data easily. Digital databases are
managed using database management systems, which store database contents, allowing data creation and
maintenance, and search and other access. The result of every query is presented as a relation.
dataset
An identifiable set of data that share common characteristics and that are managed as a subset of the data
within a database.
easting
A value on the X axis of the National Grid of Great Britain.
field
A defined area in a database record into which an item of data or value is entered.
header
Supplemental data at the beginning of a file.
identifier
An identifier that is primarily intended to provide unique and unambiguous feature identification for the
purposes of exchanging feature-based information between computer systems, or associating data within a
computer system.
JavaScript
A programming language for web browsers used primarily for front-end interaction.
JSON
JSON (JavaScript Object Notation) is a lightweight data interchange-format, returning data in the javascript
object format.
mandatory
An action, parameter or process that must be undertaken.
OS Open Names API – user guide and technical specification © Crown copyright Page 27 of 28
metadata
Graphical or textual information about the content, quality, condition, origins, and characteristics of data.
National Grid
A unique referencing system that can be applied to all Ordnance Survey maps of Great Britain at all scales. It
provides an unambiguous spatial reference for any place or entity in Great Britain.
northing
A value on the Y axis of the National Grid of Great Britain.
object
A real-world entity associated with land and property.
optional
An action, parameter or process that may be undertaken.
point
A pair of coordinates.
REST
Representational state transfer – an architectural style used by the world wide web.
RESTful API
An API that follows the RESTful architectural style.
URI
A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or
physical resource.
XML
Extensible Markup Language. A flexible way to create common information formats and share both the
format and the data on the Internet, Intranets, and elsewhere. XML is extensible because, unlike HTML, the
markup tags are unlimited and self-defining. XML is a simpler and easier to use subset of the Standard
Generalised Markup Language (SGML), the standard for how to create a document structure.
OS Open Names API – user guide and technical specification © Crown copyright Page 28 of 28
Customer Service Centre, Ordnance Survey,
Adanac Drive, Southampton, United Kingdom, SO16 0AS
+44 (0)3456 050505 (General enquiries)
+44 (0)3456 050504 (Welsh helpline)
+44 (0)2380 056146 (Textphone)
[email protected]
www.os.uk
Ordnance Survey © Crown copyright 2015
D05300_58
OS
OPEN NAM ES
API
USER GUIDE
AN D
TECH NICAL
SPECIFICATION