Querying date ranges in the ODS FHIR API

Organisation Data Service (ODS)
,
1

Hi all,

I am using the two queries:

https://api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?lastChangeDate=lt2023-05-04&lastChangeDate=gt2023-05-02

https://api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?lastChangeDate=gt2023-05-02

To return ODS API records between two dates or since a date. It seems there is a limit on the number of records returned in the response. How do I navigate this? in the ORD API there was a paging system, allowing us to loop through the pages, but I can’t see anything in the documentation for this.

I can see there is a way to limit the responses by adding “_count”, but no way to specify that you want as many as you can.

Thanks for any help,

Thomas.

2

Hi Thomas

ODS are investigating your query, liaising with the NHS England API Management Team, we will share a response asap.

Thanks

Laura

3

Hi Thomas,

The response size limit is based on payload, not number of records returned (so you could have lots of smaller records or fewer larger records returned). The payload limit is set to 10mb - set by NHS England’s API Management (APIM) team for all NHSE APIs to maintain speed and performance.

We’re further querying how a user would be informed if they hit the 10mb limit and will update. In the meantime, you can:

  • Determine how many records meet your criteria before trying to retrieve them all using “_summary=count”:

https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?activeRoleCo…

  • Then control how many records you get back at a time (to avoid exceeding the response size limit) using “count” to just get the first n results:

https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?activeRoleCo…

  • Then make a subsequent call for the next n records starting from the “offset” record number

https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?activeRoleCo…

  • Keep making those subsequent calls, incrementing the offset each time, until you hit the amount you retrieved from the “_summary=count” call.
4

Hi Thomas,

If the 10mb response size limit is exceeded then you’ll receive an error response with an HTTP status of 422 (Response exceeds APIM size limit).

APIM error handling guidance is available here: https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling

Thanks,

Sophie