Documentation

Content API documentation

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/content/acne with a valid subscription key subscription‑key: {subscription-key} 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.

Examples

curl -v -X GET "https://api.nhs.uk/conditions/acne" -H "subscription-key: {subscription key}"
<?php
// Replace pageUrl with a page you want to call.
$pageUrl = 'https://api.nhs.uk/conditions/acne';
// Replace {subscription-key} with your subscription key found here: https://developer.api.nhs.uk/developer.
$subscriptionKey = "{subscription-key}";

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => $pageUrl,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
            // Request headers
            'subscription-key:'.$subscriptionKey,
            'Accept: "application/json"',
              )
          ));

$response = curl_exec($curl);
$err  = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    $obj = json_decode($response);
    echo "<pre>";
    print_r($obj);
    echo "</pre>";
}
?>
# This script is using Python3
import urllib.request
import urllib.parse

# Replace pageUrl with a page you want to call.
pageURL = "https://api.nhs.uk/conditions/acne"
# Replace {subscription-key} with your subscription key found here: https://developer.api.nhs.uk/developer.
subscriptionKey = "{subscription-key}"

request_headers = {
  "subscription-key": subscriptionKey,
  "Accept": "application/json",
  "User-Agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
}

request = urllib.request.Request(pageURL, headers=request_headers)
contents = urllib.request.urlopen(request).read()
print(contents)
  // You will need to include the NuGet package RestSharp.

using System;
using RestSharp;

public class Program
{
	public static void Main()
	{
		// Replace pageUrl with a page you want to call.
		var pageURL = "https://api.nhs.uk/conditions/acne";
		//Replace {subscription-key} with your subscription key found here: https://developer.api.nhs.uk/developer.
		var subscriptionKey = "{subscription-key}";

		var client = new RestClient(pageURL);
		var request = new RestRequest();
		request.Method = Method.GET;
		request.AddHeader("Accept", "application/json");
		request.AddHeader("subscription-key", subscriptionKey);
		IRestResponse response = client.Execute(request);
		var content = response.Content;
		Console.WriteLine(content);


	}


}


    // You will need to have jQuery running on your webpage to run this script.

    $(function() {
       // Replace pageUrl with a page you want to call.
       var pageUrl = "https://api.nhs.uk/conditions/acne";
       // Replace {subscription-key} with your subscription key found here: https://developer.api.nhs.uk/developer.
       var subscriptionkey = "{subscription-key}";
     $.ajax({
         type: 'GET',
         url: pageUrl,
         headers: {
          'subscription-key':subscriptionkey,
          'Content-Type':'application/json'
      },
         dataType: 'json',
         success: function (data) {
           console.log(data)
         }
     });


     });

  

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/developer.
Accept application/json
application/xml

Endpoints

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 following list shows all the Endpoints that are available for our APIs under the domain https://api.nhs.uk.

You can use the filters at the top of the page and on the right hand side to only show the Endpoints that are relevant to your specific API(s).

Name Method Endpoint Parameters SchemaType
Behind the Headlines
All GET /news startDate
endDate
order
page
SearchResultsPage
Topic GET /news/{topic} startDate
endDate
order
page
SearchResultsPage
Specific Page GET /news/{topic}/{pageURL} - WebPage
Health A-Z
All pages GET /conditions startDate
endDate
order
page
category
topic
orderBy
synonyms
genre
SearchResultsPage
Condition GET /conditions/{condition} - MedicalWebPage
CollectionPage
Specific Page GET /conditions/{condition}/{subPage} - MedicalWebPage
WebPage
CollectionPage
Live Well
All pages GET /live-well startDate
endDate
order
page
category
orderBy
SearchResultsPage
Topic GET /live-well/{topic} - WebPage
Specific Page GET /live-well/{topic}/{subPage} - WebPage
Medicines
All pages GET /medicines startDate
endDate
order
page
category
orderBy
SearchResultsPage
Medicine GET /medicines/{medicine} - MedicalWebPage
Specific Page GET /medicines/{medicine}/{subPage} - MedicalWebPage
Videos
All videos GET /videos startDate
endDate
order
page
topic
orderBy
SearchResultsPage

Parameters

The following URL parameters are available to use on the SearchResultsPage to filter the results.

Parameter Type Value Description
startDate string YYYY-MM-DD Filters articles which are equal or greater than the startDate based on the orderBy parameter.
endDate string YYYY-MM-DD Filters articles which are equal or less than the endDate based on the orderBy parameter.
order string newest
oldest
asc
desc
Order by newest or oldest relating to the orderBy parameter.
page string int The page parameter is used for paginating the results. Each page lists 25 articles.
category string A-Z Filters articles by their first letter and lists the results without pagination. This can be used to create an A-Z index and usually uses the least amount of calls to retrieve all page articles.
orderBy string YYYY-MM-DD The values work alongside the startDate, endDate and orderBy parameters but they are not required. If datePublished is selected without the other parameters then it will show 25 items ordered by the newest date.
topic string int Page Number, listed by 25 articles.
synonyms string int Page Number, listed by 25 articles.
genre string condition
medicine
news
livewell
hub
Page Number, listed by 25 articles.

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 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:

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.

Elements

Within the mainEntityOfPage property, our content is chunked up into various elements. Here is a list of all elements which are used on the NHS website.

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

Tracking

You must ensure that where such tracking pixels/tag are provided, they are implemented as required and remain in place at all times to enable usage tracking to create a monthly report, aggregated across all syndication partners, detailing total page view. You can find the tracking pixel under the interactionStatistic:

"interactionStatistic": [{
  "interactionService": {
    "url": "<img style='border: 0; width: 1px; height: 1px;' alt='' src='https://statse.webtrendslive.com/dcs2221tai1ckz5huxw0mfq86_1m2w/njs.gif?dcsuri=&wt.cg_n=Syndication&wt.cg_s=&synduserid=&syndreviewdate='/>",
    "@type": "Website",
    "name": "Webtrends tracking pixel"
  },
  "@type": "InteractionCounter"
}]

If you are using the API on a platform where a tracking pixel is not compatible (mobile app) then you will need to supply us with a monthly report on usage. Please contact syndication.service@nhs.net for more information.

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 by feed.

Content as follows: Behind The Headlines - no less than once every 24 hours; all other syndicated content - 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. You can view the complete agreement here.

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 your details on your profile.

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.