Ordnance Survey Places API

Use this API for looking up and validating addresses, typically before updating patient details in the Personal Demographics Service.

You can:

• identify UK addresses
• verify the address records you are capturing against authoritative data from Ordnance Survey’s AddressBase® Premium and AddressBase® Premium - Islands
• make requests using a full or partial address, a postcode, or a Unique Property Reference Number (UPRN)
• find addresses closest to a given point
• find all the known addresses within a user-defined area, bounding box or circle
• verify an address before updating a patient's details in the Personal Demographics Service

This API is a third party API recommended for UK government services.

Data update frequency

The address, geometry and UPRN data is available for the UK and Isle of Man.  The address and UPRN data is available for Jersey and Guernsey.

This data is updated every 6 weeks.

Requests

This API has seven types of request in two categories.

Capture and verification category:

• Find - a free text search for quick use

• Postcode - a search based on a property’s postcode

• UPRN - a search that takes a UPRN as the search parameter

GeoSearch category:

• Nearest - finds the closest address to a given point

• Bounding box - finds all addresses inside a bounding box

• Radius - finds all addresses that intersect a given circle

• Polygon - finds all addresses in a polygon or multi-polygon object

For more information, see the Technical Specification.

There are no particular restrictions on what this API can be used for.

It can be used free of charge by public sector organisations in England, Scotland and Wales, including the NHS. This includes use by software developers building software for the public sector.

For more details, see Onboarding.

To use this API:

1. Get a license - see Onboarding.

2. Follow the steps in the Getting Started Guide on the OS Data Hub.

3. Check out some Code Examples for help in querying this API.

This API is in production.

Use this API for looking up and validating addresses, typically before updating patient details in the Personal Demographics Service with one of:

• the Personal Demographics Service FHIR API
• the Personal Demographics Service HL7 V3 API

We intend to deprecate the Gazetteer SOAP API and replace it with this API.

This API is supported by Ordnance Survey. It is available 24 hours a day, 365 days a year with 99.9% uptime.

It is subject to a fair use transaction limit as explained in the API Service Terms.

This API is a RESTful API.

It returns responses in XML or JSON.

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN).
For more details see Network access for APIs.

This API is application-restricted, meaning:

• the calling application is authenticated
• the end user is not authenticated

In particular, it uses API key authentication, so you'll need to get an API key for your application. For details, see Onboarding.

For more information on security, see the Technical Specification.

This API does not provide an environment for testing. Use the production environment to test your application.

To get access to the production environment, see Onboarding.

To get access to the production environment you need an API key.

How you do this depends on your organisation type.

Public sector organisations, including NHS organisations

To use the API free of charge, become a PSGA member. Then you can manage your own API keys in the OS Data Hub.

General practices

General practices cannot become PSGA members, but are unlikely to be building their own software - see 'Private sector software developers' below.

Ordnance Survey has agreed that the OS Places API can be used free of charge within general practice for the specific purpose of ensuring address quality within their Patient Administration System (PAS), so long as address changes are also reflected in the Personal Demographics Service.

Private sector software developers

To use the API free of charge, sign a 'contractor licence' with a PSGA member.

If you are building software for a specific NHS organisation, sign a contractor licence with them. This is likely to be based on Ordnance Survey's standard Public Sector Contractor Licence. If they are not already a PSGA member, they might need to become one first.

Alternatively, you can sign a single contractor licence with us if you are:

• building software for use in multiple NHS organisations
• or building software for general practice
• and your software is integrated with the Personal Demographics Service

To do this, contact us. Once we have checked your use case, we will direct you to sign our customised OS Places contractor licence.

Your sponsoring PSGA member, whether it's us or another organisation, will supply you an OS Places API key using the OS Data Hub.

You do not need a separate API key for each NHS organisation your software is used in - you can use the same API key for all of them.

If we are your sponsoring PSGA member, you must issue Ordnance Survey's Public sector license for end users to each end user organisation that uses your software.

For details of interactions for this API, see the Technical Specification.

This API is owned and maintained by Ordnance Survey. 

If you have any issues, you can get help and support.