Skip to main content
Creating a new NHS England: Health Education England, NHS Digital and NHS England have merged. More about the merger.

Why we're opening up our API catalogue

Business analyst Matthew Firth talks about the expansion of NHS Digital’s application programming interface (API) catalogue which, for the first time, will now include external APIs.

Historically, we have only represented NHS Digital APIs in our API catalogue. The reason is that the Developer hub was set up as a space where API consumers can learn about the NHS Digital onboarding journey and identify the APIs which they’d like to onboard with. It made sense to only represent our NHS Digital APIs in there and aimed to avoid confusion or dilute our onboarding journey for external suppliers and partners. 

A collage of street signs set against a map

What has changed?

Our strategy hasn’t necessarily changed – we still want to present NHS Digital APIs on the catalogue, talk about our onboarding journey and how we make integration easier. However, we are mindful that we are in partnership with other organisations, either across the NHS or externally, and it makes sense to present relevant external specifications on the API catalogue as well as our own. 

We have recently brought our first external API onto the catalogue – the Ordnance Survey (OS) Places API – owned and maintained by Ordnance Survey. 

Why OS Places?

People building healthcare software need an API that can retrieve and validate UK-based postal addresses, which is used for things like updating a patient’s address in the Personal Demographics Service (the national database of patient demographic information). 

Our own API that does this, Gazetteer, is at the beginning of its sunsetting journey and has recently been deprecated.  This means that we won’t allow any more API consumers to onboard to it. While nothing changes in the short-to-medium term on licensing, service level agreements, and support offering, we will retire the Gazetteer API in the next couple of years, subject to all API consumers migrating away from it.  

In the longer term we would like to have one version of the truth – the API catalogue.

Instead of creating a new API to replace Gazetteer ourselves, we decided to add OS Places to our catalogue. It is a well-established API that is recommended by UK Government Services as the API of choice for looking up and validating addresses. Additionally, the Government Digital Service has mandated the use of the unique property reference number (UPRN), something that the existing Gazetteer API did not use whilst OS Places does – another good reason to include it in our catalogue. OS Places has already been used across the NHS including by the London Ambulance Service and so its addition to the NHS Digital API catalogue should only increase its usage in other digital services in the NHS. 

We are encouraging consumers to migrate to, or onboard with OS Places if they are developing new software, as soon as realistically possible. It’s free to use for public sector organisations if they become a Public Sector Geospatial Agreement (PSGA) member or for private sector software developers if they sign a contractor licence with a PSGA member.  

Updating our API catalogue filters

As NHS Digital has been the only owner of the APIs within the API catalogue, we have never needed to provide a tag or filter to represent ownership.  Now that we are presenting external APIs, we have updated the filter option to show the name of the owning organisation of each API.  Currently the only filter option available is OS Places, but as the list grows, the ability to filter by owner will become more comprehensive.  

What next?

We are already talking to other areas of the NHS about including their APIs in the API catalogue, as well as hosting them on our API platform, and several are interested in doing this.  In the longer term we would like to have one version of the truth – the API catalogue – and move documentation away from older or more legacy platforms. 

We’ve worked hard to improve the API catalogue by making our API specifications more accessible. We will work with owners of external APIs to ensure that the information which we present is accurate and provides the level of detail that API consumers need, whilst staying consistent with the layout and style of the NHS Digital API specifications.   

Get involved

If you have any feedback, please contact us.

Related subjects

Learn about what APIs we offer, and how you can connect to them
Matthew Firth, Business Analyst in our API Management team, explains how we’ve worked with users to ensure our resources for developers don’t exclude people with accessibility needs.
Dr Munish Jokhani, Assurance Lead for API Management at NHS Digital explains how we retire our APIs and how developers can get involved in the process.
Sam Perera, API Delivery Manager at NHS Digital, explains how we are making it easier to use our APIs.


Last edited: 16 November 2022 1:58 pm