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:
- Pick a page on the NHS website, for example:
https://www.nhs.uk/conditions/acne - Make a note of the path, for example:
conditions/acne - Using a tool such as cURL, Postman or your web browser, make a GET request to
https://api.nhs.uk/conditions/acnewith a valid subscription keysubscription-key: YOUR_SUBSCRIPTION_KEY_GOES_HEREin the request header. - 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.
| Header key | Header value |
|---|---|
| subscription-key | You can view your subscription keys at: https://developer.api.nhs.uk/profile. |
| Accept | application/json application/xml |
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, chq, news, 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
mainEntityOfPagewhere as an automatic listing usinghasPart, like the social care and support pages.
Here is a list of properties for each schema page type we are currently using:
| MedicalWebPage | WebPage | SearchResultsPage | CollectionPage |
| @context | @context | @context | @context |
| @type | @type | @type | @type |
| author | author | author | author |
| license | license | license | license |
| copyrightHolder | copyrightHolder | copyrightHolder | copyrightHolder |
| interactionStatistic | interactionStatistic | interactionStatistic | interactionStatistic |
| genre | genre | genre | genre |
| breadcrumb | breadcrumb | breadcrumb | breadcrumb |
| name | name | name | headline |
| alternativeHeadline | description | description | name |
| description | mainEntityOfPage | significantLink | description |
| mainEntityOfPage | dateModified | url | hasPart |
| dateModified | lastReviewed | url | |
| lastReviewed | relatedLink | mainEntityOfPage | |
| relatedLink | url | ||
| url |
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'.
| Module | Description | Schema name |
|---|---|---|
| Overview | Summary of what the condition is and any key symptoms, treatments or causes | overview (description and text) |
| Symptoms summary | Short summary of some of the main symptoms of the condition | symptoms (description) |
| Symptoms | Content on all the main symptoms of the condition | symptoms (text) |
| Treatment summary | Short summary of the main treatments for the condition | treatments_overview (description) |
| Self-care | Content on what patients can do to manage the condition | self_care (text) |
| Medical treatments | Content on medical treatments for the condition | other_treatments (text) |
| Causes summary | Short summary of the main causes of the condition | causes (description) |
| Prevention summary | Short summary of the main ways to help prevent the condition | prevention (description) |
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.