Rating and reviews API documentation

Quick start

To get started:

  1. Using a tool such as curl, Postman or your web browser, make a GET request to the relevant endpoint, as specified in this document, with a valid subscription key subscription‑key: {subscription-key} in the request header.
  2. 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/comments/comments?orgType=HOS" -H "subscription-key: {subscription key}"
<?php
// Replace pageUrl with a page you want to call.
$pageUrl = 'https://api.nhs.uk/comments/comments?orgType=HOS';
// 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/comments/comments?orgType=HOS"
# 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/comments/comments?orgType=HOS";
		//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/comments/comments?orgType=HOS";
       // 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

The following list shows all the Endpoints that are available for our APIs under the domain https://api.nhs.uk.

Name Method Endpoint Parameters
Ratings and reviews GET /comments/comments orgType
odsCode
status
offset
limit
fromDate
toDate
Aggregated ratings GET /comments/ratings odsCode
Rating questions GET /moderation/questions orgType
The following endpoints require access which can only be aquired by emailing the syndication team.
Submit a comment POST /moderation/comment
Submit a response POST /moderation/response
Remove a comment DELETE /moderation/comment commentID
publisher
ref
Comment status POST /moderation/comment/status commentID

Parameters

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

Parameter Type Value Description
orgType string HOS The organisation type for which you want records to be returned.
  • DEN (dental)
  • OPT (optician)
  • HOS (hospital)
  • PHA (pharmacy)
  • GPB (general practice)
  • TRU (trust)
  • IND (independent sector hospital)
  • SCL (social care location)
  • CLI (clinic)

A list of organisation types are also available within the service search api.

odsCode string RRV03 An ODS code/NACS code which is used by the organisation identifier.

You can use the service search api to find an ODS code of an organisation.

offset int 0 Offset is the position in the dataset of a particular record. By specifying offset, you will retrieve a subset of records starting with the offset value. Offset normally works with limit (see below), which determines how many records to retrieve starting from the offset value.
limit int 100 Limit the number of records returned.
fromDate string YYYY-MM-DD The start date for records you want to return.
toDate string YYYY-MM-DD The end date for records you want to return.
status string published
removed
The comment status.
The following properties require access which can only be aquired by emailing the syndication team.
commentId string
publisher string
ref string

Properties

The fields included in the ratings data are shown in the table below.

Property Description
Comment
commentId A unique identifier to specify each comment.
commentRef
responseID A unique identifier to specify each response.
odsCode The primary identifier that specifies a provider of NHS services. Each comment is linked to one (and only one) odsCode. This is referred to as a NACS code.
commentOriginalURL The URL where each comment appears on nhs.uk.
title The title given to the comment by the person leaving it.
commentText The text of the comment.
dateSubmitted The date the comment was submitted.
lastUpdated The date the comment was last updated.
sentimentScore Sentiment score is the sentiment analysis score between 0.00 and 1.00.
department The hospital department, if one has been given. This is a free text field. Reference data will be provided through a search / profile API, with departments being unique to each organisation.
publisherID This is a unique identifier specifying the organisation submitting the comment through our inbound rating and reviews API. 0 is defaulted to NHS Digital.
publishersCommentRef Reference id supplied by third party who has submitted the rating and review.
screenName The commenter’s chosen screen name.
status Whether the comment is published or removed.
ratings This featured the rating for each question. See Endpoints to see the full question being asked to the user.
visit Includes the month and year in which the commenter visited the service.
Response
commentId A unique identifier to specify each response.
commentRef
commentOriginalURL The URL where each comment appears on nhs.uk.
commentText The text of the response.
dateSubmitted The date the response was submitted.
lastUpdated The date the response was last updated.
sentimentScore Sentiment score is the sentiment analysis score between 0.00 and 1.00.
odsCode The primary identifier that specifies a provider of NHS services. Each comment is linked to one (and only one) odsCode. This is referred to as a NACS code.
publisherID This is a unique identifier specifying the organisation submitting the comment through our inbound rating and reviews API. 0 is defaulted to NHS Digital.
publishersCommentRef Reference id supplied by third party who has submitted the rating and review.
status Whether the comment is published or removed.
removeReportLink
respondingTo

Request body

The following submissions requires access which can only be aquired by emailing the syndication team.

Submit a comment (example)
{
  "author": "user@domain.com",
  "screenName": "Annonymous",
  "title": "This is a Test Comment with Ratings",
  "commentText": "This is the body of the comment",
  "visit": {
    "month": 1,
    "year": 2020
  },
  "publishersCommentRef": "1234",
  "commentOriginalURL": "https://www.domain.com/comments/1234",
  "department": "General Surgery",
  "ipAddress": "192.168.0.125",
  "odsCode": "RRV03",
  "ratings" : [{"question" : "10012", "rating" : 3},
    {"question" : "10017", "rating" : 1},
    {"question" : "10013", "rating" : 1},
    {"question" : "10016", "rating" : 5},
    {"question" : "10015", "rating" : 5}]
  }
Submit a response (example)
{
  "author": "user.name@nhs.net",
  "screenName": "John Smith",
  "title": "This is a Test Response",
  "commentText": "This is the body of the comment",
  "publishersCommentRef": "RESP1",
  "commentOriginalURL": "https://www.domain.com/comments/1234/response",
  "department": "",
  "ipAddress": "192.168.0.125",
  "odsCode": "RRV03",
  "respondingTo": {
    "PublishersCommentRef": "1234"
  }
}

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

"tracking": "<img style='border: 0; width: 1px; height: 1px;' alt='' src='https://nhsdigital.d3.sc.omtrdc.net/b/ss/nhsuk-prod/1/JS-2.9.0-L8UK/654321?c27=&c28=&c29=&c75=web&events=event23'>"

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.

Usage caps for posting comments and responses

You are not to submit more than 100 comments 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.

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