Documentation Content API

All our content APIs are structured using the already well adopted Schema.org vocabulary. This page goes through the various schema types which are available in the API along with our interpretation of property values.

Quick start

To get started:

1. Pick a page on the NHS website, for example: https://www.nhs.uk/conditions/acne
2. Make a note of the path, for example: conditions/acne
3. Using a tool such as cURL, Postman or your web browser, make a GET request to https://api.nhs.uk/conditions/acne with a valid subscription key subscription-key: YOUR_SUBSCRIPTION_KEY_GOES_HERE in the request header.
4. You’ll receive a JSON response structured using schema.org and the fields for this are explained in the following documentation.

Example

curl -v -X GET "https://api.nhs.uk/conditions/acne" -H "subscription-key: YOUR_SUBSCRIPTION_KEY_GOES_HERE"

Authentication and Headers

To make a REST API call, you must include request headers including the subscription-key header with a subscription key. All subscriptions under NHS website APIs are available in JSON and XML and you can select your preference under the Accept header. If you do not choose an Accept header then the default output will be JSON.

Endpoints and parameters

View the JSON output from any page on the NHS website by replacing www. with api., providing you are using a valid subscription-key in the header.

For example, the json output for https://www.nhs.uk./conditions/acne can be accessed using https://api.nhs.uk/conditions/acne. The endpoints and their parameters for our APIs under the domain https://api.nhs.uk are available within our NHS APIs documentation.

Schema page types

Throughout the NHS website we have various page models which are defined using the @type property. It is a good thing to implement each page type into your product, as multiple page types can be used within in a single genre (conditions, live-well, medicines, etc).

• MedicalWebPage - A web page that provides medical information. We are using this for our Health A-Z and medicines articles.
• WebPage - This is the default type we are using and is featured in conditions, live-well and news.
• SearchResultsPage - The search results page is used for all our indexes and you can use various parameters to filter the results.
• CollectionPage - Across the NHS website, there are hub sections which contain multiple child articles. Type 1 Diabetes and Social Care and Support are good examples of these. Type 1 Diabetes uses a manual listing so articles are listed in the mainEntityOfPage where as an automatic listing using hasPart, like the social care and support pages.

Here is a list of properties for each schema page type we are currently using:

It is worth noting that the genre property is what we use to define which section the article sits in, and the @type is used to define how that article is structured.

Modularised NHS content

As well as whole pages of conditions content, you can also now get some smaller, more specific sections (called “modules”). Find out more about our modularised content We currently have modularised content for 250 of the most popular medical conditions on the NHS website.

Available conditions include:

• chickenpox
• urinary tract infections
• high blood pressure
• chest infections
• irritable bowel syndrome

Each topic has up to 8 content modules you can choose from. The modules are listed within the 'hasPart' property within those condition articles. The short summary is shown under the 'description' property within a 'hasPart' and the module is within the 'text' property of a 'hasPart'.

Attribution

Any syndicated content must incorporate the following attribution (credit) to the NHS website:

The logo should be clearly visible and in line with the associated content on every web page that contains the syndicated content. You should also link this logo to the relevant page on the NHS website that the content has been supplied from. This URL is supplied as part of the feed under author:

"author": {
"url": "https://www.nhs.uk",
"logo": "https://www.nhs.uk/nhscwebservices/documents/logo1.jpg",
"email": "nhswebsite.servicedesk@nhs.net",
"@type": "Organization",
"name": "NHS website"
}

If you are displaying NHS syndicated content in a context where a functional link back to the article on the NHS website is not possible then you should use the following attribution (credit):

From www.nhs.uk

Caching

Caching of all syndicated content is recommended, and you should do so where possible. Unless otherwise notified to you by the Syndication team, you should refresh cached syndicated content page views no less than once every 7 days. If instructed to refresh cached syndicated content, you must do so immediately.

Usage caps

You are not to call the APIs over 4,000 times in any one hour unless you have notified such intention to the Syndication team in advance and they have confirmed in writing that they are content for you to do so. When using the trial subscription on initial sign up you will only be able to run 10 calls/minute up to a maximum of 1,000 calls per month. A full subscription caps usage at 4,000 calls per hour.

Standard licence terms

By using the NHS website syndicated content, you agree to be bound by the standard licence terms.

Contact details

You must provide accurate contact details that must be kept up to date while you are receiving syndicated content. Failure to keep contact details updated will breach the agreement and may result in your subscription being disabled. You can check and update your details on the change details page.

Support

If you need help with the implementation of any of our digital products or simply want to find out more about what we have on offer, please get in touch.