Skip to main content

Directory of Healthcare Services API - version 3

Find information about NHS healthcare services, including lists of NHS organisation types, organisations, and coronavirus (COVID 19) walk-in sites.

This specification is written from an OAS file.

Page content

Overview

Use this API to find information about organisations that provide NHS healthcare services, NHS organisation types, and coronavirus (COVID-19) walk-in sites.

You can:

  • retrieve a list of organisation types, for example, GP practices or hospitals
  • search for NHS organisations that provide healthcare services listed in NHS service near you, for example, Leeds General Infirmary
  • search for coronavirus (COVID-19) walk-in sites

This API does not support the FHIR standard, but we have a mapping of how its response fields could be mapped to it. For details, see DoHS API guide to FHIR mappings.

Who can use this API

This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. To do this, contact us. You must do this before you can go live (see ‘Onboarding’ below).

Related APIs

The following APIs are related to this API:

API status and roadmap

This API is in development, meaning:

  • it is available for testing in the integration environment
  • we expect to make breaking changes based on developer feedback

Roadmap

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog. If you have any other queries, please contact us.

Service level

This API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays. For more details, see service levels.

Technology

This API is RESTful.

This API does not support the FHIR standard, but we have a mapping of how its response fields could be mapped to it. For details, see DoHS API guide to FHIR mappings.

Network access

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN). For more details see Network access for APIs.

Security and authorisation

This API is application-restricted, meaning we authenticate the calling application but not the end user.

To use this API, use the following security pattern:

Environments and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/service-search-api/
Integration test https://int.api.service.nhs.uk/service-search-api/
Production Not yet available

Sandbox testing

Our sandbox environment:

  • is for early developer testing
  • only covers a limited set of scenarios
  • is open access, so does not allow you to test authorisation

For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.

Our integration test environment is for formal integration testing.

Integration testing

Our integration test environment:

  • is for formal integration testing
  • includes authorisation, with options for appliation-restricted access
  • test data is a close copy of the production data

For more details see integration testing with our RESTful APIs.

Rate Limiting

The integration test environment is rate limited to 1500 requests per week and 1 request per second.

Onboarding

This API is not yet available for onboarding.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Endpoints

Search for organisation types

get /organisationtypes

Overview

Use this endpoint to get, filter or search the organisation types.

For more information on how to use search identifiers with this endpoint, see DoHS API guide to search identifiers and service codes.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

Scenario Request Response
All organisation types / HTTP status 200 with all organisation types
Single organisation type search=pharmacy HTTP status 200 with a single organisation type
No organisation types found search=nothing HTTP status 200 with no organisation types
Invalid API version No api-version parameter HTTP status 404 with problem description

You can try out the sandbox using the 'Try this API feature' on this page.

Request

Query parameters
Name Description
api-version

BigDecimal

Default value: 1

The API version number must be supplied as a query parameter. This must be 1.

Allowed values: 1

Required
search

String

The text to search for. All searchable fields are searched by default unless searchFields is specified.

When searching searchable fields, the search text itself is tokenized, so multiple terms can be separated by white space, for example search=hello world.

To match any term, use * which can be useful for boolean filter queries. Omitting this parameter has the same effect as setting it to *.

Optional
searchMode

String

Default value: any

Defaults to any. Specifies whether any or all of the search terms must be matched in order to count the document as a match.

Allowed values: any, all

Optional
searchFields

String

A comma-separated list of field names to search for the specified text. This field works in conjunction with the search field.

Example search field - searchFields=ODSCode

Omitting this parameter has the same effect as setting it to *.

Optional
queryType

String

Default value: simple

When set to simple, search text is interpreted using a simple query language that allows for symbols such as +, * and "".

When the query type is set to full, search text is interpreted using the Lucene query language which allows field-specific and weighted searches.

The following example is a search over independent terms, with a requirement that all matching documents include pool.

For more information, see Simple query syntax in Azure Cognitive Search.

Example using simple query type:

queryType=simple

search=budget hotel +pool

searchMode=all

The next example shows in-field search and term boosting. It looks for hotels where the category field contains the term budget.

Any documents containing the phrase recently renovated are ranked higher as a result of the term boost value.

For more information, see Lucene query syntax in Azure Cognitive Search.

Example using full query type:

queryType=full

search=category:budget AND \'recently renovated\'^3

searchMode=all

Allowed values: simple, full

Allowed values: simple, full

Optional
$skip

BigDecimal (int32)

The number of search results to skip. For example, $skip:25 returns the entries after the first 25 entries in the search results.

Optional
$top

BigDecimal (int32)

Default value: 50

The number of search results to retrieve. The default is 50.

Optional
$count

Boolean

Default value: false

Optional, defaults to false. Specifies whether to fetch the total count of results.

This is the count of all documents that match the search and $filter parameters, ignoring $top and $skip.

Setting this value to true may have a performance impact. The count returned is an approximation.

If you’d like to get only the count without any documents, you can use $top=0.

Optional
$orderBy

String

A list of comma-separated expressions to sort the results by. Each expression can be either a field name or a call to the geo.distance() function.

Each expression can be followed by asc to indicate ascending, and desc to indicate descending. The default is ascending order.

This $orderBy routine orders the results by the distance from the geography point included in the expression.

The geography point can be a position from where you are and the results are ordered by how local they are.

For more information, see Simple query syntax in Azure Cognitive Search.

Example: $orderby=geo.distance(Geocode, geography'POINT(-0.76444095373153675 52.000820159912109)')

Optional
$select

String

A list of comma-separated fields to include in the result set.

If unspecified or set to *, all fields marked as retrievable in the schema are included in the projection.

Example: $select=ODSCode,OrganisationName,Contacts,Address1,Address2,Address3,City,Postcode,OrganisationSubType

Optional
$filter

String

A structured search expression in standard OData syntax.

The $filter parameter specifies inclusion or exclusion criteria for returning matches in search results.

For more information on using the $filter, see OData $filter syntax in Azure Cognitive Search.

Examples:

Filter results by pharmacies that are EPS-enabled and classed as 'community', that is, ServiceCode is EPS0001 and OrganisationTypeID is PHA and SubType is Community:

$filter=Services / any (x: x/ServiceCode eq 'EPS0001' ) and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'Community'

Filter results that match a postcode, that is Postcode field is NG16:

$filter=search.ismatch('NG16', 'Postcode')

Filter results by Postcode is CW9 and OrganisationTypeId is a dentist:

$filter=search.ismatch('CW9', 'Postcode') and OrganisationTypeId eq 'DEN'

For details on organisation types and service codes, see organisation and service codes.

Optional

Response

HTTP status: 200

Search response

Body

Content type: application/json

Examples

Schema

Name Description
HTTP status: 4XX

Below are examples of potential HTTP status codes and their associated error codes, which could be returned in the event of a fault. Guidance on error handling within BaRS can be found here.

HTTP status Error code Description
400 SEND_BAD_REQUEST The API was unable to process the request.
400 REC_BAD_REQUEST The Receiver has responded stating the message was malformed.
401 SEND_UNAUTHORIZED The API deemed you unauthorized to make this request.
401 REC_UNAUTHORIZED The receiver deemed you unauthorized to make request.
403 SEND_FORBIDDEN Missing or Expired Token.
404 PROXY_NOT_FOUND No related people exist for given NHS number.
404 REC_NOT_FOUND Patient record for given NHS number has been invalidated and not superseded by another NHS number.
405 SEND_METHOD_NOT_ALLOWED HTTP Verb is not correct for this scenario.
405 REC_METHOD_NOT_ALLOWED Receiver does not allow this.
405 PROXY_METHOD_NOT_ALLOWED Proxy does not allow this.
406 SEND_NOT_ACCEPTABLE Senders message had an incorrect content type defined for a response.
408 REC_TIMEOUT The downstream domain processing has not completed within the configured timeout period.
409 SEND_CONFLICT
409 REC_CONFLICT
409 PROXY_CONFLICT
422 SEND_UNPROCESSABLE_ENTITY Message was not malformed but deemed unprocessable.
422 REC_UNPROCESSABLE_ENTITY Message was not malformed but deemed unprocessable.
422 PROXY_UNPROCESSABLE_ENTITY Message was not malformed but deemed unprocessable.
429 SEND_TOO_MANY_REQUESTS The user has sent too many requests in a given amount of time
429 REC_TOO_MANY_REQUESTS The user has sent too many requests in a given amount of time
Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-Id from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-Id from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object

Search for organisations

get /

Overview

Use this endpoint to find information about services provided by NHS organisations.

For more information on how to use search identifiers with this endpoint, see DoHS API guide to search identifiers and service codes.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

Scenario Request Response
All organisations No parameters HTTP status 200 with all organisations
Single organisation search=DN601 HTTP status 200 with single organisation
No organisations found search=no-organisation HTTP status 200 with no organisations
Invalid API version No api-version parameter HTTP status 404 with problem description

You can try out the sandbox using the 'Try this API feature' on this page.

Request

Query parameters
Name Description
api-version

BigDecimal

Default value: 2

The API version number can be supplied as a query parameter.

Required
search

String

The text to search for. All searchable fields are searched by default unless searchFields is specified.

When searching searchable fields, the search text itself is tokenized, so multiple terms can be separated by white space, for example search=hello world.

To match any term, use * which can be useful for boolean filter queries. Omitting this parameter has the same effect as setting it to *.

Optional
searchMode

String

Default value: any

Defaults to any. Specifies whether any or all of the search terms must be matched in order to count the document as a match.

Allowed values: any, all

Optional
searchFields

String

A comma-separated list of field names to search for the specified text. This field works in conjunction with the search field.

Example search field: searchFields=ODSCode

Optional
queryType

String

Default value: simple

When set to simple, search text is interpreted using a simple query language that allows for symbols such as +, * and "".

When the query type is set to full, search text is interpreted using the Lucene query language which allows field-specific and weighted searches.

The following example is a search over independent terms, with a requirement that all matching documents include pool.

For more information, see Simple query syntax in Azure Cognitive Search.

Example using simple query type:

queryType=simple

search=budget hotel +pool

searchMode=all

This particular example shows in-field search and term boosting. It looks for hotels where the category field contains the term budget.

Any documents containing the phrase recently renovated are ranked higher as a result of the term boost value.

For more information, see Lucene query syntax in Azure Cognitive Search.

Example using full query type:

queryType=full

search=category:budget AND \'recently renovated\'^3

searchMode=all

Allowed values: simple, full

Optional
$skip

BigDecimal (int32)

The number of search results to skip. For example, $skip:25 returns the entries after the first 25 entries in the search results.

Optional
$top

BigDecimal (int32)

Default value: 50

The number of search results to retrieve. The default is 50.

Optional
$count

Boolean

Default value: false

Optional, defaults to false. Specifies whether to fetch the total count of results.

This is the count of all documents that match the search and $filter parameters, ignoring $top and $skip.

Setting this value to true may have a performance impact. The count returned is an approximation.

If you’d like to get only the count without any documents, you can use $top=0.

Optional
$orderBy

String

A list of comma-separated expressions to sort the results by. Each expression can be either a field name or a call to the geo.distance() function.

Each expression can be followed by asc to indicate ascending, and desc to indicate descending. The default is ascending order.

This $orderBy routine orders the results by the distance from the geography point included in the expression.

The geography point can be a position from where you are and the results are ordered by how local the results are.

For more information, see Simple query syntax in Azure Cognitive Search.

Example: $orderby=geo.distance(Geocode, geography'POINT(-0.76444095373153675 52.000820159912109)')

Optional
$select

String

A list of comma-separated fields to include in the result set.

If unspecified or set to *, all fields marked as retrievable in the schema are included in the projection.

Example: $select=ODSCode,OrganisationName,Contacts,Address1,Address2,Address3,City,Postcode,OrganisationSubType

Optional
$filter

String

A structured search expression in standard OData syntax.

The $filter parameter specifies inclusion or exclusion criteria for returning matches in search results.

For more information on using the $filter, see OData $filter syntax in Azure Cognitive Search.

Examples:

Filter results by Pharmacies that are EPS-enabled and classed as 'Community', that is, ServiceCode is EPS0001, Organisation Type is PHA and Sub Type is Community:

$filter=Services / any (x: x/ServiceCode eq 'EPS0001' ) and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'Community'

Filter results that match our postcode, that is Postcode field is NG16:

$filter=search.ismatch('NG16', 'Postcode')

Filter results by Postcode is CW9 and `OrganisationTypeId" is a dentist:

$filter=search.ismatch('CW9', 'Postcode') and OrganisationTypeId eq 'DEN'

For details on organisation types and service codes, see organisation and service codes.

Optional

Response

HTTP status: 200

Search Response

Body

Content type: application/json

Examples

Schema

Name Description
HTTP status: 4XX

Below are examples of potential HTTP status codes and their associated error codes, which could be returned in the event of a fault. Guidance on error handling within BaRS can be found here.

HTTP status Error code Description
400 SEND_BAD_REQUEST The API was unable to process the request.
400 REC_BAD_REQUEST The Receiver has responded stating the message was malformed.
401 SEND_UNAUTHORIZED The API deemed you unauthorized to make this request.
401 REC_UNAUTHORIZED The receiver deemed you unauthorized to make request.
403 SEND_FORBIDDEN Missing or Expired Token.
404 PROXY_NOT_FOUND No related people exist for given NHS number.
404 REC_NOT_FOUND Patient record for given NHS number has been invalidated and not superseded by another NHS number.
405 SEND_METHOD_NOT_ALLOWED HTTP Verb is not correct for this scenario.
405 REC_METHOD_NOT_ALLOWED Receiver does not allow this.
405 PROXY_METHOD_NOT_ALLOWED Proxy does not allow this.
406 SEND_NOT_ACCEPTABLE Senders message had an incorrect content type defined for a response.
408 REC_TIMEOUT The downstream domain processing has not completed within the configured timeout period.
409 SEND_CONFLICT
409 REC_CONFLICT
409 PROXY_CONFLICT
422 SEND_UNPROCESSABLE_ENTITY Message was not malformed but deemed unprocessable.
422 REC_UNPROCESSABLE_ENTITY Message was not malformed but deemed unprocessable.
422 PROXY_UNPROCESSABLE_ENTITY Message was not malformed but deemed unprocessable.
429 SEND_TOO_MANY_REQUESTS The user has sent too many requests in a given amount of time
429 REC_TOO_MANY_REQUESTS The user has sent too many requests in a given amount of time
Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-Id from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-Id from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object

Search for organisations by postcode or place

post /search-postcode-or-place

Overview

Use this endpoint to search for information about services provided by NHS organisations, listed in the service search on the NHS website, filtered by postcode or place name.

For more information on how to use search identifiers with this endpoint, see DoHS API guide to search identifiers and service codes.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

Scenario Request Response
Place found search=manchester HTTP status 200 with 2 locations
Postcode found search=WC1N 3JH HTTP status 200 with 50 locations
Postcode not found search=LS42PB HTTP status 500 with problem description
No search parameter No search parameter HTTP status 500 with problem description
Invalid API version No api-version parameter HTTP status 404 with problem description

You can try out the sandbox using the 'Try this API feature' on this page.

Request

Query parameters
Name Description
api-version

BigDecimal

Default value: 2

Specify the version of the API. MUST be 2.

Allowed values: 2

Required
search

String

Search query term.

When searching searchable fields, the search text itself is tokenized, so multiple terms can be separated by white space, for example search=hello world.

To match any term, use *. Omitting this parameter has the same effect as setting it to *.

Optional
latitude

BigDecimal

The latitude parameter for geospacial searches.

Optional
longitude

BigDecimal

The longitude parameter for geospacial searches.

Optional
Body
Optional

Content type: application/json

Schema

Name Description
object

Response

HTTP status: 200

Postcode search results

Body

Content type: application/json

Example

Schema

Name Description
HTTP status: 401

Unauthorized

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 404

Not found

Body

Content type: application/json

Example

Schema

Name Description
object
HTTP status: 429

Too Many Requests

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Schema

Name Description
object

Last edited: 27 October 2023 12:14 pm