NHS APIs Ratings and Reviews API

Ratings and reviews for NHS organisations listed in the service search on the NHS website.

This API is accessed through HTTP and returns data in a JSON format.

Base URL

All requests to this API should start with the following base URL:

https://api.nhs.uk/comments

API Version

The API version number can be supplied as a query parameter:

?api-version=1.0

Authentication and Headers

Your request must include a subscription-key header with a valid subscription key.

Request header keys and values
Header key	Header value
subscription-key	Login or register to get an API key to use this API

Endpoints

An endpoint is added to the base URL to create the full request URL. Some APIs have more than 1 type of endpoint you can use.

Comments

Lists all comments for an organisation type or organisation.

Endpoint

GET `/Comments`

Parameters

Name	Type	Allowed	Default	Description
orgType query	`string`	DEN, OPT, HOS, PHA, GPB, TRU, IND, SCL, CLI		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 query	`string`			An ODS code/NACS code which is used by the organisation identifier. Example: RRV03. You can use the service search api to find an ODS code of an organisation.
status query	`string`	published, removed	published	The comment status.
offset query	`integer`			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. Example: 0.
limit query	`string`			Limit the number of records returned. Example: 100.
fromDate query	`string`			The start date (YYYY-MM-DD) for records you want to return.
toDate query	`string`			The end date (YYYY-MM-DD) for records you want to return.

Responses

200 - Successful response

                          {
  "comments": [
    {
      "comment": {
        "commentId": "46e341dc-1c80-ea11-a811-000d3a7ed688",
        "commentRef": "927264",
        "responseID": "",
        "odsCode": "RRV03",
        "commentOriginalURL": "",
        "title": "Great care",
        "commentText": "I had to attend on Thursday 16 after midnight with stomach pains. The nurse who placed the kunola placed it without difficulty as I have collapsed veins and the doctor who saw read my file and knew my issue in order to treat it. She asked me if I needed food to eat as I did not eat all day and then asked how I was going home at that hour in the morning  (my husband was going to pick me up). The doctor was very efficient, studied the file, kind, humane etc. Etc. What more can one say for such service. I was home within 3 hours from arriving at A&E",
        "dateSubmitted": "2020-04-16T20:00:13Z",
        "lastUpdated": "2020-04-17T07:08:58Z",
        "sentimentScore": 0,
        "department": "Accident and emergency services",
        "publisherID": "0",
        "publishersCommentRef": "927264",
        "screenName": "Ruth Timan",
        "status": "Published",
        "removeReportLink": false,
        "ratings": [
          {
            "question": "10012",
            "rating": 5
          },
          {
            "question": "10017",
            "rating": 5
          },
          {
            "question": "10013",
            "rating": 5
          },
          {
            "question": "10014",
            "rating": 5
          },
          {
            "question": "10016",
            "rating": 3
          },
          {
            "question": "10015",
            "rating": 5
          }
        ],
        "visit": {
          "month": 4,
          "year": 2020
        }
      },
      "response": null
    }
  ]
}

Comments

Endpoint

POST `/Comments`

Parameters

Name	Type	Required	Allowed	Default	Description
body body

Responses

200 - Successful response

CommentById

Endpoint

GET `/CommentById`

Responses

200 - Successful response

Ratings

Aggregated ratings

Endpoint

GET `/Ratings`

Parameters

Name	Type	Required	Allowed	Default	Description
odsCode query	`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.

Responses

200 - Successful response

                          {
  "aggregatedRatings": [
    {
      "question": "10015",
      "numOfRatings": 108,
      "totalScore": 400,
      "averageScore": 3.7037037037037037
    },
    {
      "question": "10012",
      "numOfRatings": 99,
      "totalScore": 426,
      "averageScore": 4.303030303030303
    },
    {
      "question": "10017",
      "numOfRatings": 101,
      "totalScore": 402,
      "averageScore": 3.98019801980198
    },
    {
      "question": "10013",
      "numOfRatings": 102,
      "totalScore": 405,
      "averageScore": 3.9705882352941178
    },
    {
      "question": "10014",
      "numOfRatings": 98,
      "totalScore": 390,
      "averageScore": 3.979591836734694
    },
    {
      "question": "10016",
      "numOfRatings": 82,
      "totalScore": 323,
      "averageScore": 3.9390243902439024
    }
  ]
}

400 - You have sent a request that the server could not understand. This is likely because you have not added the odsCode parameter.

Publishers

Endpoint

GET `/publishers`

Responses

200 - Successful response

Count

Endpoint

GET `/Count`

Responses

200 - Successful response

Count

Endpoint

POST `/Count`

Responses

200 - Successful response

Publishers (clone)

Publishers

Endpoint

GET `/clone-6107d/publishers`

Responses

200 - Successful response

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 all content supplied through our API is recommended where possible. Unless otherwise notified by the syndication team, you should refresh cached content at least once every 7 days. If instructed to refresh cached our content, you must do so immediately.

Certain topics on the NHS website need to be refreshed more frequently than every 7 days. Find out about content not covered by our standard terms and conditions.

Usage caps

When using a trial subscription, 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. You are not to call the APIs over 4,000 times in any one-hour period, unless you have notified the syndication team in advance and they have confirmed in writing that you can do so.

Standard licence terms

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

Your contact details

You must provide accurate contact details that must be kept up to date while you are using our content. Failure to keep contact details updated is a breach of our licence terms and may result in your subscription being disabled. You can check your details on your profile.

Help and support

If you need help using any of our APIs , please email the NHS website service desk at nhswebsite.servicedesk@nhs.net.