# This is an OpenAPI Specification (https://swagger.io/specification/)
# for the nhs-website-content-api owned by NHS England (https://digital.nhs.uk/)
openapi: "3.0.0"
info:
title: "NHS Website Content API v2"
version: "Computed and injected at build time by `scripts/set_version.py`"
description: |
## Overview
This API provides content from the [NHS website](https://www.nhs.uk) as JSON, to be consumed programmatically and used by your application.
You can reuse the content from the following sections of the NHS website:
* [Health A to Z (conditions)](https://www.nhs.uk/conditions/)
* [Medicines A to Z](https://www.nhs.uk/medicines/)
* [Mental health](https://www.nhs.uk/mental-health/)
* [Live Well](https://www.nhs.uk/live-well/)
* [Pregnancy](https://www.nhs.uk/pregnancy/)
* [NHS services](https://www.nhs.uk/nhs-services/)
* [Common health questions](https://www.nhs.uk/common-health-questions/).
You cannot use this API to:
* [find services near you](https://www.nhs.uk/nhs-services/services-near-you/)
* get Ratings and Reviews of NHS services.
Pick a page from one of these sections on the [NHS website](https://www.nhs.uk/).
Make a note of the path in the page URL (the bit that appears after '`https://www.nhs.uk/`').
You can then use this path to make API calls to the 'Integration test' environment and the 'Production' environment like so …
**Integration test environment**
`https://int.api.service.nhs.uk/nhs-website-content/YOUR_PATH_GOES_HERE`
**Production environment**
`https://api.service.nhs.uk/nhs-website-content/YOUR_PATH_GOES_HERE`
## Who can use this API
Anyone can use this API for any purpose, so long as they have agreed to the [Online connection agreement](https://digital.nhs.uk/developer/guides-and-documentation/online-connection-agreement) during the [onboarding process](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process) and they include an [attribution](#overview--attribution) as outlined below.
## Attribution
Any syndicated content must incorporate the following attribution (credit) to the NHS website:
The logo should be clearly visible and in line with the associated content on every web page that contains the syndicated content. You should also link this logo to the relevant page on the NHS website that the content has been supplied from.
```
```
This URL is supplied as part of the JSON response under author:
```
"author": {
"url": "https://www.nhs.uk",
"logo": "https://www.nhs.uk/nhscwebservices/documents/logo1.jpg",
"email": "nhswebsite.servicedesk@nhs.net",
"@type": "Organization",
"name": "NHS website"
}
```
If you are displaying NHS syndicated content in a context where a functional link back to the article on the NHS website is not possible then you should use the following attribution (credit):
```
From www.nhs.uk
```
## Modularised content
The standard content available through our syndication service is based on the full pages on the NHS website. With our modularised content, you can instead choose to use shorter, more specific sections of content (called “modules”) from our pages. This means you can show your users only the content that’s most relevant to them. You can also use this content more easily in services like apps and voice assistants.
For more details see [Modularised NHS content](https://digital.nhs.uk/developer/api-catalogue/nhs-website-content/modularised-nhs-content#about-our-modularised-content).
## API status
This API has moved from the [NHS website developer portal](https://developer.api.nhs.uk/).
It is currently [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).
## Service level
This API is a [bronze service](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
## Technology
This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
Page objects conform to global [schema.org](https://schema.org/) standards.
## Network access
This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).
To use this API with [NHS smartcards](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers), the end user needs an HSCN connection, although internet-facing alternatives to smartcards are available.
For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
## Security and authorisation
This access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user.
To use this access mode, use the following security pattern:
* [Application-restricted RESTful API - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication).
## 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 endpoint are shown in the endpoints section, under response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.
## Environments and testing
| Environment | Base URL |
| ----------------- | ---------------------------------------------------------------------- |
| Sandbox | `https://sandbox.api.service.nhs.uk/nhs-website-content/` |
| Development | Not used |
| Integration test | `https://int.api.service.nhs.uk/nhs-website-content/` |
| Production | Not available yet |
### Sandbox testing
Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
* is for early developer testing
* only covers a limited set of scenarios
* is open access, so does not allow you to test authorisation
The sandbox environment includes the following 48 mocked endpoints
API v2 root
Conditions (Health A to Z)
Medicines
Mental health
Live Well
Pregnancy
NHS Services
Common health questions
For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.
Alternatively, you can try out the sandbox using our Postman collection:
[](https://app.getpostman.com/run-collection/222854-abafff02-a96d-4259-9c0d-2f4d3fd6d4bf)
### Integration testing
Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):
* is for formal integration testing
* includes authorisation via an API Key
For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).
## Onboarding
You need to get your software approved by us before it can go live with this API. We call this onboarding.
The [onboarding process](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process) for this API is currently in development.
During this process you will be asked agree to the [Online connection agreement](https://digital.nhs.uk/developer/guides-and-documentation/online-connection-agreement).
## Caching
Caching of all responses from the NHS website content API is recommended, and you should do so where possible, unless otherwise notified to you by NHS Digital. The cached data should be refreshed no less than once every 7 days. If instructed to refresh cached NHS website content, you must do so immediately.
## Usage caps
Calls to this API are rate limited as follows:
| Environment | Rate limit |
| ----------------- | ------------------------------- |
| Sandbox | 60 requests per minute |
| Integration test | 10 requests per minute |
| Production | 6000 requests per minute |
contact:
name: "NHS Website Content API v2 Support"
url: "https://digital.nhs.uk/developer/help-and-support"
email: api.management@nhs.net
servers:
- url: "https://sandbox.api.service.nhs.uk/nhs-website-content"
description: Sandbox environment.
- url: "https://int.api.service.nhs.uk/nhs-website-content"
description: Integration test environment.
- url: "https://api.service.nhs.uk/nhs-website-content"
description: Production environment.
paths:
/conditions:
parameters:
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/order"
- $ref: "#/components/parameters/page"
- $ref: "#/components/parameters/category"
- $ref: "#/components/parameters/synonyms"
- $ref: "#/components/parameters/childArticles"
- $ref: "#/components/parameters/status"
get:
summary: Get all pages in the Health A to Z
operationId: get-conditions
description: |
## Overview
Use this endpoint to get details of pages in the [Health A to Z](https://www.nhs.uk/conditions/).
Passing in no parameters returns all pages under 'conditions'.
The response is limited to 25 child pages and is paginated.
There are a number of query parameters that filter the output.
responses:
"200":
description: |
A valid query for the conditions.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/ConditionsHealthAToZ.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/conditions/*:
parameters:
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/modules"
get:
summary: Get details of a condition page
operationId: get-condition-page
description: |
## Overview
There is an endpoint for each page under the Health A to Z, for example https://www.nhs.uk/conditions/chickenpox.
This can be used to get specific information about individual topics.
There is only one query parameter for these pages:
| Query parameter | Description | Type |
| ----------------- | ---------------------------------------------------------------------- | ----------- |
| modules | If topic is modularised, only return these modules | boolean |
# Modularisation
We modularise some of our content, meaning that individual parts of the page can be reused. If a page is modularised, content appears in the `hasPart` field.
responses:
"200":
description: |
A valid query which returns a page object for the chosen page
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/ConditionsContentPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/medicines:
parameters:
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/startDate"
- $ref: "#/components/parameters/endDate"
- $ref: "#/components/parameters/order"
- $ref: "#/components/parameters/page"
- $ref: "#/components/parameters/category"
- $ref: "#/components/parameters/orderBy"
get:
summary: Get all pages in the Medicines A to Z
operationId: get-medicines
description: |
## Overview
Use this endpoint to get details of pages in the [Medicines A to Z](https://www.nhs.uk/medicines).
Passing in no parameters returns all pages under 'medicines'.
The response is limited to 25 child pages and is paginated.
There are a number of query parameters that filter the output.
## Ordering by dates
The `orderBy` parameter can be `dateModified`, `lastReviewed` and `nextReview`. By default if any of the `orderBy` parameters are chosen the results are sorted by newest first.
However, the `orderBy` parameter can be used with the `startDate` and `endDate` parameters to filter down to the desired date. `startDate` and `endDate` should be given in the YYYY-MM-DD format.
For example `https://api.nhs.uk/medicines?startDate=2022-01-01&orderBy=dateModified`
responses:
"200":
description: |
A valid query for medicines.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/MedicinesAToZ.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/medicines/*:
parameters:
- $ref: "#/components/parameters/apikey"
get:
summary: Get specific medicine page
operationId: get-medicine-page
description: |
## Overview
There is an endpoint for each page under the Medicines A to Z, for example https://www.nhs.uk/medicines/amoxicillin.
This can be used to get specific information about individual medicines.
responses:
"200":
description: |
A valid query for medicines.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/MedicinesContentPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/mental-health:
parameters:
- $ref: "#/components/parameters/apikey"
get:
summary: Get content from the mental health hub
operationId: get-mental-health
description: |
## Overview
The [mental health hub](https://www.nhs.uk/mental-health/) contains a number of navigational and content pages.
The content of the page is taken from the `mainEntityOfPage` part of the response. This includes the navigational links to child pages.
At the top level, modularised content of child pages is highlighted by the `hasPart` field. In child pages, only the individual page is shown.
responses:
"200":
description: |
A valid query for the mental health hub.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/MentalHealthHubPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/live-well:
parameters:
- $ref: "#/components/parameters/apikey"
get:
summary: Get content from the Live Well hub.
operationId: get-live-well
description: |
## Overview
The [Live Well hub](https://www.nhs.uk/live-well/) contains a number of navigational and content pages.
The content of the page can be taken from the `mainEntityOfPage` part of the response. This includes the navigational links to child pages.
At the top level, modularised content of child pages is highlighted by the `hasPart` field. In child pages, only the individual page is shown.
responses:
"200":
description: |
A valid query for the Live Well pages.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/LiveWellHubPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/pregnancy:
parameters:
- $ref: "#/components/parameters/apikey"
get:
summary: Get content from the pregnancy hub
operationId: get-pregnancy
description: |
## Overview
The [pregnancy hub](https://www.nhs.uk/pregnancy/) contains a number of navigational and content pages.
The content of the page can be taken from `mainEntityOfPage`. This includes the navigational patterns to child pages.
At the top level, child modularised content is highlighted by the `hasPart` field. In child pages, only the individual page is highlighted.
responses:
"200":
description: |
A valid query for the pregnancy hub.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/PregnancyHubPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/nhs-services:
parameters:
- $ref: "#/components/parameters/apikey"
get:
summary: Get content from the NHS services hub
operationId: get-nhs-services
description: |
## Overview
The [NHS services hub](https://www.nhs.uk/nhs-services/) contains a number of navigational and content pages.
The content of the page can be taken from `mainEntityOfPage`. This includes the navigational patterns to child pages.
At the top level, child modularised content is highlighted by the `hasPart` field. In child pages, only the individual page is highlighted.
responses:
"200":
description: |
A valid query for the NHS services hub.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/NhsServicesHubPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
/common-health-questions:
parameters:
- $ref: "#/components/parameters/apikey"
get:
summary: Get content from the common health questions hub
operationId: get-common-health-questions
description: |
## Overview
The [common health questions hub](https://www.nhs.uk/common-health-questions/) contains a number of navigational and content pages.
The main page contains significant links to topic pages, which then contain significant links to the content pages.
Content pages use the 'question' schema.org [question](https://schema.org/Question) property.
responses:
"200":
description: |
A valid query for the common health questions pages.
content:
application/json:
schema:
$ref: components/schemas/WebPage.json
example:
$ref: components/examples/CommonHealthQuestionsHubPage.json
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | --------------------------------------------- |
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
| 403 | ACCESS_DENIED | User cannot perform this action. |
| 404 | RESOURCE_NOT_FOUND | Page not found. |
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
components:
headers:
apikey:
$ref: components/schemas/ApiKey.yaml
parameters:
apikey:
name: apikey
in: query
description: The API key required to send a successful request.
required: true
schema:
type: string
example: "aTfjAa9vHfnmaQNABgSXGFCS9SFVMLWc"
startDate:
name: startDate
in: query
description: Earliest date filter, works with orderBy.
required: false
schema:
type: string
example: "2020-01-01"
endDate:
name: endDate
in: query
description: Latest date filter, works with orderBy.
required: false
schema:
type: string
example: "2021-01-01"
order:
name: order
in: query
description: Order by "newest" or "oldest".
required: false
schema:
type: string
example: "newest"
page:
name: page
in: query
description: Page number, used to filter paginated results.
required: false
schema:
type: string
example: "1"
category:
name: category
in: query
description: Filters child pages by letters "A" to "Z".
required: false
schema:
type: string
example: "A"
orderBy:
name: orderBy
in: query
description: works alongside startDate and endDate. Options are "dateModified", "lastReviewed" and "nextReview".
required: false
schema:
type: string
example: "lastReviewed"
synonyms:
name: synonyms
in: query
description: Include multiple listings for pages with more than one name.
required: false
schema:
type: boolean
example: true
childArticles:
name: childArticles
in: query
description: Include child pages of a topic within results under property subjectOf.
required: false
schema:
type: boolean
example: true
status:
name: status
in: query
description: Filter by "published" or "unpublished".
required: false
schema:
type: string
example: "published"
modules:
name: modules
in: query
description: If topic is modularised, only return these modules.
required: false
schema:
type: boolean
example: true