Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Build | Organisation Data Service (ODS) Search

How to use the FHIR ODS Lookup API to perform searches on ODS, containing examples that use different technologies to perform a search. This includes HAPI Java, C# .NET and cURL.

0. References

1. Overview

Within the NHS, there is a requirement to identify organisations across the Health and Social Care landscape. The Organisation Data Service (ODS) provides access to the repository of publishing codes that identify these organisations and provide valuable information that can reduce administration and improve data quality. ODS provides 3 file types:

  • Full files which provide a complete snapshot of all organisations.
  • Quarterly amendments provide amended or new records over a three month period.
  • Monthly amendments provide amended or new records over a one month period.
ODS Overview
ODS Data Feeds

ODS Lookup API provides an API using a RESTful interface following a resource API pattern to provide access to the Organisational Data Service (ODS) database.

This is particularly suited to:

  • A health portal securely exposing organisational information to browser based plugins.
  • Medical devices which need to access organisational information.
  • Mobile devices used by physicians which need to establish organisational information.
  • Web based EPR/EHR applications which wish to provide dynamic updates of organisation details.
  • Any low resource application which exposes organisational search functionality.
  • A facade providing a simple API to a complex interface.

2.1 Foundation

Organisation Lookup FHIR Actor Diagram
Organisation Lookup FHIR Actor Diagram

The ODS API Lookup can use any of the search parameters defined in the ODS Lookup API.

What we have just described is shown in the diagram below. When entering the url an ODS Lookup FHIR Query is performed and an ODS Lookup response is returned with an XML body and a HTTP response code.

Basic Process Flow ODS Search FHIR
Basic Process Flow

3. Search Parameters

Examples of using different technologies to perform a search.

Parameter Parameter Type Description HAPI Java C# .NET cURL
_id/identifier token Search for ODS records based on their logical or business identifier
_lastUpdated date Search for ODS records based on their last updated date
name string Search for ODS records based on their name, including modifiers.
active token Search for ODS records based on their status, active or inactive.
address-postalcode string Search for ODS records based on their address postcode
address-city string Search for ODS records based on their address city
ods-org-role token Search for ODS records based on their role
ods-org-primaryRole token Search for ODS records based on their primary role
_count number Control the number of results returned per page
_summary=count string Return a count of the matching resources

3.1 Search using ODS Code

To search for ODS records based on their logical or business identifier.

3.1.1 HAPI Java

3.1.2 C# .NET

3.1.3 cURL

3.2 Search using last updated date

To search for ODS records based on their last updated date.

3.2.1 HAPI Java

3.2.2 C# .NET

3.2.3 cURL

3.3 Search using name

To search for ODS records based on their name, including modifiers.

3.3.1 HAPI Java

3.3.2 C# .NET

3.3.3 cURL

3.4 Search using active status

To search for ODS records based on their status, active or inactive.

3.4.1 HAPI Java

3.4.2 C# .NET

3.4.3 cURL

3.5 Search using address postcode

To search for ODS records based on their address postcode.

3.5.1 HAPI Java

3.5.2 C# .NET

3.5.3 cURL

3.6 Search using address city

To search for ODS records based on their address city.

3.6.1 HAPI Java

3.6.2 C# .NET

3.6.3 cURL

3.7 Search using Organisation role

To search for ODS records based on their role.

3.7.1 HAPI Java

3.7.2 C# .NET

3.7.3 cURL

3.8 Search using an Organisations primary role

To search for ODS records based on their primary role.

3.8.1 HAPI Java

3.8.2 C# .NET

3.8.3 cURL

3.9 Search and limit the results per page

With the scale of the ODS data, the results returned from certain queries could be extensive and require a method for browsing the details returned. It is possible to control the number of results returned using the _count parameter.

3.9.1 HAPI Java

3.9.2 C# .NET

3.9.3 cURL

3.10 Search and return a count

Just return a count of the matching resources, without returning the actual matches

3.10.1 HAPI Java

3.10.2 C# .NET

3.10.3 cURL

Tags: development

All content is available under the Open Government Licence v3.0, except where otherwise stated