Our API is currently in beta. So the service described here is subject to change.

Use of the API requires an API key, which you can get by contacting us. This means we can know who you are, so that as the API evolves (and it will!) we can let you know.

Posting API

We have a basic, read-only posting API available. You can use it to retrieve a single posting or a collection of postings.

Some things you'll need to know:

• It's a RESTful API
• It only accepts HTTP GET
• The data comes back as plain old XML
• You'll need an API key, which you add to the query string

Retrieving a single posting

To retrieve a single posting go here:

http://www.patientopinion.org.uk/api/rest.svc/v1/postings/{postingid}?apikey={apikey}

• This returns a single posting, together with the tags, health services and responses linked to that posting
• You put the ID of the posting you want in place of {postingid}
• You put your API key in place of {apikey} (duh!)
• If the ID refers to a non-existent or unpublished posting, or to a response, you'll get a 404

Retrieving a collection of postings

To retrieve a collection of postings go here:

http://www.patientopinion.org.uk/api/rest.svc/v1/postings/search?param1={param1}&param2={param2}&apikey={apikey}

• This returns a collection of postings, together with the tags, health services and responses linked to each posting
• You put your search parameters in place of {param1}, etc. You can add as many parameters as you like
• You put your API key in place of {apikey}
• If the search returns no postings, you'll get a 404

Search parameters

The API supports the following search parameters:

• postingas:the role of the posting author, e.g. patient, carer, relative: consult the dropdown list on the "share your story" page for the options available
• postingtype: story, concern, thank you, suggestion, tip
• postingsource: "po" if you just want stories posted via Patient Opinion, "nhsc" if you just want stories posted via NHS Choices
• phrase: a phrase you want to be in the posting text
• healthservice:The ID (NACS code) of a health service the posting is about. You can find the ID you want by looking at the URL of the page about that service
• tag: a tag linked to the posting
• frompopulation: the ONS/ODS code of an area the posting has come from. This can be the code for an NHS PCT or SHA, or for a local government district council, county, unitary authority, metropolitan area or London borough.

Paging parameters

There are two optional paging parameters:

• skip: skips the first S postings in the set (default is zero)
• take: returns the first T postings in the set (default is 10, maximum is 100)

Used together, skip and take will allow you to page through a collection of postings.

Search mode

There is one further parameter, which when used changes the sort order of postings returned, and allows you to "pick up" from a later point in the posting set.

The default ordering is in order of the posting submission date, from most recent to least recent.

• startfrom: starts the search from a given posting ID, and returns postings in ascending posting ID order

API key

You'll need an API key to use our API.

Once you have a key you just add it to the query string like this:

• apikey={xxx}

To get an API key, get in touch.

Back