The documentation contained within outlines how the feeds work, their structure and so on. Use these pages to help you implement the content successfully.
We’ve created an example of how to build a services application, using a scripting language (RUBY in this case). This should allow you to see how the process works, and can be applied across services, as well as organisations. It doesn’t matter what language you use – this should show you how to get started. You can see the entire project at GitHub, which also contains an explanation of what we’ve done. We hope to release more of these over the coming months.
Question and answer sets are available from the question & answer service which is accessible for each service type. This replaces the need to request the questions for ratings from the syndication team.
An example implementation for hospitals is:
The overall rating question (called the friends & family test) is missing one possible answer which is Answer ID: 0 Answer Text: Don’t know
It should read as follows:
Question ID: 7
Question Text: Friends and Family
Answer ID: 0
Answer Text: Don’t know
Answer ID: 1
Answer Text: Extremely unlikely
Answer ID: 2
Answer Text: Unlikely
Answer ID: 3
Answer Text: Neither likely or unlikely
Answer ID: 4
Answer Text: Likely
Answer ID: 5
Answer Text: Extremely likely
The NHS Choices Syndication Definition talks through how to post comments using the API to the NHS Choices platform. Currently this service is available for GPs, hospitals, dentists, opticians, pharmacies and care homes. In order to use it, you’ll need to have signed up for an API key, and have an understanding of how to use .xml via POST method. In order to test, it is recommended you use a tool such as http://code.google.com/p/poster-extension/ (for Firefox browser) or similar.
As well as agreeing to the Comment Capture T&Cs, you’ll also need to read the comment capture guidance notes, and refer to the organisation responses, which can be found at http://v1.syndication.nhschoices.nhs.uk/organisations/gppractices/questionsandanswers?apikey=[APIKEY] (assuming your organisation type is GP). In addition, you’ll need your own unique posting organisation ID – speak to your syndication manager to obtain this. Finally, before reporting issues, it’s a good idea to check your .xml is valid. Refer not only to the expected response codes (2.1.1), but also to an .xml validator, such as http://www.xmlvalidation.com/index.php?id=1&L=0. Please note that white space may cause an issue.
When using the scorecard data within syndication, the list of metrics is fairly long. Use the scorecardMetrics document to identify the metrics you wish to use. If you have any queries about scorecard, please speak to your syndication manager, who will put you in touch with the data team, who’ll be able to explain how it works.
When a comment is moderated, before being posted to NHS Choices, the moderation team will assign it one or more tags, identifying what the comment is about. This is exposed in the syndication feeds, in the element
with each individual tag being an <li> item. Using the syndication feeds, either by taking the comment feed and using the requisite elements, or using the ‘Comments by tag’ functionality within the API. Using
for example, it’s possible to refine the comments by tag. The commentTags document contains a list of all available tags.
This post deals with the differences between organisation and services data, and is especially useful if you are integrating any data from the find and choose services side of NHS Choices.
Organisations and services are different, both in terms of what they supply, how they are rendered in the feeds, and the level of data associated with them. All organisations and services should contain basic information such as contact details and mapping coordinates (allowing you to plot on mapping software). In simplistic terms, the organisations are parent organisations – administrative bodies like Clinical Commissioning Groups, or physical entities like GP surgeries and hospitals. These bodies and entities usually have a physical location, which in the case of GPs and hospitals can be visited, but will also provide specific services, at these (or other) locations. The administrative bodies are usually responsible for procuring and delivering these services, and so a link exists between the parent provider (CCG), the deliverer (GP), and the service (asthma clinic). Organisations generally have more information, profiles which give further information on things like facilities, reviews and a list of the services provided. You can see an example of an hospital organisation profile here.
Services are split into two categories – services provided by a parent organisation, such as A&E, which is provided by a hospital, and services which sit outside this relationship, such as weight loss centres and sports clubs. These will generally contain less information. You can see an example of a service here. Some services (for example stop smoking) will have multiple services, as these are delivered through different means; in the case of stop smoking, which has four services, these cover smoking cessation clinics, stop smoking services provided by GPs, smoking cessation advice and services provided by pharmacies, and local stop smoking services. If you want the full range of data, you’ll need to implement multiple services. Speak to your syndication manager for further information and guidance.
For further information about how the parent/child relationship works, and information on services and organisations, please see the syndication documentation, the outline of the .xml for both (Organisation and Service Overview), and the elemental structure (Organisation Elements).
Please note: we have recently moved to a new way of representing our service data – you experience a number of 404 pages, where data has been moved to a new location. We are in the process of analysing the data paths to remove these errors; in the meantime, please handle them as you would normal 404 pages elsewhere.
To consume the content in its structure, you’ll need to determine that structure first. In order to do this, you’ll need to query the API to bring back the required data structure. This can be done using HTML or JSON, and in some cases XML. We would recommend you use XML to integrate the content in all cases, as it represents the optimum data set. Where possible, use the atom or rss representations. Because the topics are dynamic, and contain no actual content (they just reflect the structure of the data as it appears), the calls must be made to ascertain what sits beneath the structure. This can be seen as follows:
The article ‘Track your drinking’ resides at
The API structure can be broken down as follows for this piece of content
http://v1.syndication.nhschoices.nhs.uk/ – the root of the syndication platform
livewell/ – the main topic, which contains sub topics and articles
topics/ – determines how you are accessing the section. In the case of Live Well, this would either by by Topic, Group or Artcles Since
alcohol/ – determines the sub topic level
/alcoholtracker – determines article level, at which point the content exists
To access all topics for Live Well, the API call would look like:
At this point, the XML, JSON or HTML would contain a list of the topics, and their respective URIs, such as:
and so on. By returning this data, you see what sub topics currently exist for the parent topic Live Well. As each sub topic has a URI, it then becomes possible to retrieve the list of articles at sub topic level. Note that at this point, it becomes impossible to view the content as XML – data must now be accessed as HTML or JSON, due to the dynamic nature of the data. Note also that the data is identified as either Featured or Main; this will change depending on what health information is pertinent at any given time:
- <ahref=”http://v1.syndication.nhschoices.nhs.uk/livewell/topics/alcohol/alcohol-units?apikey=xxx”>Alcohol units
- <ahref=”http://v1.syndication.nhschoices.nhs.uk/livewell/topics/alcohol/alcoholtracker?apikey=xxx”>Track your drinking
- <ahref=”http://v1.syndication.nhschoices.nhs.uk/livewell/topics/alcohol/tipsoncuttingdown?apikey=xxx”>Tips on cutting down
Even though the data is now displaying HTML, it is still possible to identify each article, and the URI to access this (contained within the
Once you access the individual article URIs, the content is available for consumption, meaning it can be pulled into your datasets, templates, or however you choose to work with the data.
In order to comply with our terms and conditions, you’ll need to make sure that you include a logo on every page of your website where you’re syndicating NHS Choices content. You’ll also need to make sure that each piece of content links back to the originating page on NHS Choices, to protect our ownership of the content. To help you do so, we’ve embedded both the logo and the original page on the Choices website within the feed.
Assuming you are using an .xml representation:
To implement the logo, please ensure that any content you syndicate includes the
<logo> element. This will link to the image on our servers, and display it accordingly.
To implement the link back to the Choices content, please ensure that you implement the
><link rel=”alternate”> tag, which contains an href attribute which will link back to the original article on NHS Choices. You may wish to build this into the logo.
This should be done for every single piece of content you syndicate. For example, content taken for the Asthma introduction page should look like this when you implement it:
<a href="http://www.nhs.uk/conditions/asthma/Pages/Introduction.aspx"> <img src="http://www.nhs.uk/nhscwebservices/documents/logo1.jpg" /></a>
If you then syndicate the treatments page, the link should look as follows:
<a href="http://www.nhs.uk/conditions/asthma/Pages/Treatment.aspx"> <img src="http://www.nhs.uk/nhscwebservices/documents/logo1.jpg" /></a>
For an example of how this should work, see http://www.allesleyparkmedicalcentre.co.uk/Library/livewell/topics/asthma/asthma-cold-weather
Webservices Implementation and Syndication Guide details how to use the syndication feeds. It is designed as an outline guide, explaining how the feeds work. It doesn’t give the means or methods by which to integrate the feeds – you’ll need knowledge of some form of backend scripting language, such as PHP or .NET. Please refer to other documentation for guidance.