This is Care Opinion [siteRegion]. Did you want Care Opinion [usersRegionBasedOnIP]?
Care Opinion

Archived Information on this page is probably out of date

Version 1 API documentation

Error

Error updating site page. We've logged the issue, please try again later.

Update: 19 August 2016

We are currently transitioning to new (version 2) APIs. The access, scoping duration and content of our APIs is changing.

We will not be issuing any new version 1 API keys at this point. Further details are available in the version 2 documentation.

API key

Use of our API requires a key, which you can get by contacting us. This means we can know who you are, so that as the API changes we can let you know.

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.

Posting API

We have a simple, 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

https://www.careopinion.org.uk/api/v1/opinions/{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

https://www.careopinion.org.uk/api/v1/opinions?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:

  • authorrole: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
  • postingsource: "po" if you just want stories posted via Care Opinion, "co" if you just want stories posted via Care Opinion, "nhsc" if you just want stories posted via NHS Choices (England)
  • phrase: a phrase you want to be in the posting text
  • nacs: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. You can add as many as you want. Because we model health care as a tree, when you set a nacs code we return all the postings linked to that health service or any of its descendant services (i.e. the subtree).
  • tag: a tag linked to the posting. You can add as many as you want.
  • 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. You can add as many as you want.
  • treatmentfunction: the NHS code for a specialty provided by a service the posting is about
  • SubmittedOnBefore, SubmittedOnAfter: date limits for the search
  • ProgressId: the progress of a story through told (1), heard (2), has response (3), led to change (4)
  • skip: see below
  • take: see below
  • startfrom: The default ordering is in reverse order of posting submission date, from most recent to least recent. Using startfrom changes the sort order to "oldest first", and sets the minimum posting id in the set. This will allow you to page forwards in time, picking up from where you left off in a previous session.

Responses

Responses to postings are accessible in two distinct ways:

  • Within the response collection on postings retrieved through the posting API as described above
  • As a separate Response API, which returns a collection of responses

The response API is here:

https://www.careopinion.org.uk/api/v1/responses?apikey={apiKey}

This endpoint will return a collection of responses, in order of submission date (oldest first), which makes it useful for paging through latest responses.

This endpoint accepts a few parameters as follows:

  • postingsource: "po" if you just want stories posted via Care Opinion, "nhsc" if you just want stories posted via NHS Choices (England)
  • skip: see below
  • take: see below
  • startfrom: sets the lower limit for the response id (so you can pick up where you left off)
  • provideronly=true: Only includes responses which were posted by one of the providers the posting is about. This allows you to exclude responses from, for example, commissioners, patient groups, regulators, etc.

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.

;