Introduction

OpenODS is a reference data API built aspiring towards REST principles using NHS organisational data available openly from the NHS Organisation Data Service (ODS).

You are welcome to use OpenODS to support your projects as you like - all we ask is that you give us feedback and contribute any suggestions you might have to help us to continuously improve it.

If you're interested in contributing there are lots of ways you can help - so get in touch!

Endpoint

OpenODS API can be accessed at the following endpoint:

api.openods.co.uk/api

Rate Limiting

We don't apply rate-limiting to client requests as we don't see enough traffic at this point in time - but please do be considerate and avoid inadvertent DOS attacks :)

Authentication

No authentication is required to access data via the OpenODS API.

Versioning

Whilst in Alpha, the API does not use any form of versioning. Breaking changes may be made to the API although we will try and avoid this where not necessary.

In the future, we will look to introduce versioned endpoints to handle backwards-incompatible changes.

Pagination

Pagination can be used on routes which return multiple instances of a resource (e.g. /organisations) by using the offset and limit query parameters to page the results returned.

Responses containing multiple resources will include a X-Total-Count header with the total number of resources available.

At some point in the future we'll add prev / next headers to make paging through results easier but for the moment you will need to track yourself using the X-Total-Count header.

Responses

As you can only do GET requests against the API currently there are only a couple of response codes you can expect to receive.

  • 200 OK - Will be returned when a request is successful. The body will either contain a single resource object, or a list of resource objects. In the event of no results (e.g. on a request with query parameters /organisations?q=chocolate request), a 200 with an empty list will be returned.
  • 404 NOT FOUND - Will be returned when a request is unsuccessful. This will normally occur when trying to GET a single resource e.g. /organisations/RFF