Syndication Documentation

The documentation Webservices Implementation and Syndication Guide details how to use the syndication feeds, explaining how the feeds work. It doesn’t give the means or methods by which to integrate the feeds – you will need knowledge of some form of back-end scripting language, such as PHP or .NET. Additionally, you will find other related blog posts for more information about feeds, videos and other tools.

NHS Choices attribution logo for syndication

Any NHS Choices syndicated content must incorporate the following attribution (credit) to NHS Choices:

logo_content_supplied

 

The logo should be placed, above the fold, and remain clearly visible in line with the associated content on every web page that contains the NHS Choices syndicated content. You should also link this logo to the relevant page on the NHS Choices website that the content has been supplied from. This URL is supplied as part of the feed.

If you are displaying NHS Choices Syndicated Content in a context where a functional link back to the article on the NHS Choices website is not possible then you should use the following attribution (credit):

From www.nhs.uk.

Implementing services demo: using RUBY

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.

Missing Answer ID for overall rating question (friends & family test)

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:

http://v1.syndication.nhschoices.nhs.uk/organisations/hospitals/questionsandanswers?apikey=<APIKey>

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

Answers:

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

Comment capture documentation

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.

Scorecard Metrics

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.

Comment Tagging

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

<div id="commentTags">

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

http://v1.syndication.nhschoices.nhs.uk/organisations/hospitals/organisationtypecommentsbytag?apikey={APIKEY}

for example, it’s possible to refine the comments by tag. The commentTags document contains a list of all available tags.

Reporting Requirements

As part of any implementation you do, you should be ensuring that you add the

<tracking>

tag to all pages. This will amalgamate page views of our content on any part of your site where you syndicate NHS Choices information. This will help us to understand what content people are using, and in turn we can feed this back to you at a high level  helping you shape your health content.

In order to implement this, you’ll need to add the following example line of code to each page where you serve our content. Please note that the code within this element will change with each page, although the element itself will remain the same. The element appears only at article level.

As part of the acceptance of the terms and conditions, you must ensure that you add the tracking tag wherever it is present in the feeds.

Organisations and Services Overview

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.

 

Syndication and XML structure

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

http://v1.syndication.nhschoices.nhs.uk/livewell/topics/alcohol/alcoholtracker?apikey=xxx

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:

http://v1.syndication.nhschoices.nhs.uk/livewell/topics/?apikey=xxx

At this point, the XML, JSON or HTML would contain a list of the topics, and their respective URIs, such as:

Abuse

http://v1.syndication.nhschoices.nhs.uk/livewell/topics/abuse?apikey=xxx

Addiction

http://v1.syndication.nhschoices.nhs.uk/livewell/topics/addiction?apikey=xxx

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
elements above).

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.