GOV.UK Content API v1.0.0
GOV.UK Content API provides a simple and consistent way to request GOV.UK content as structured data in a predictable format. It is used within the GOV.UK website as the means for applications to lookup content in order to render it.
This API accepts HTTP requests and responds with JSON data containing the same published content as is presented on GOV.UK.
Base URL
All requests to this API should be prefixed with the following URL:
https://www.gov.uk/api/content
Content
GET /{path}
Lookup GOV.UK content by path
This is the primary interface to lookup the content required to render a page on GOV.UK
It accepts an input of the path of the page you are looking up. For
example, if you were looking up travel advice for Thailand which is
hosted on GOV.UK at https://www.gov.uk/foreign-travel-advice/thailand
you would make a request to
https://www.gov.uk/api/content/foreign-travel-advice/thailand.
If the content is available at the requested path you will receive
a ContentItem containing the structured data for that
page.
This request does not require authentication.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| path | path | string | true | The path to the content on GOV.UK e.g for https://www.gov.uk/vat-rates you’d use vat-rates
|
Example Request
curl https://www.gov.uk/api/content/vat-rates
Example Response
Examples
“`json { ”$ref": “#/components/examples/ContentItemExample” } “`Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | A content item is available at that path. | ContentItem |
| 303 | See Other | A content item at a different location is responsible for the content at this path. Learn more. | None |
| 404 | Not Found | No content item is available at that path. | None |
| 410 | Gone | The content item is no longer available at that path. | None |
Objects
ContentItem
A resource that represents a piece of content on GOV.UK. It contains metadata that describe common attributes shared between all content, a details for the particular content and a links field to describe relationships with other content.
Sample JSON
”`json { “$ref”: “#/components/examples/ContentItemExample” } “`Fields
| Name | Type | Required | Description |
|---|---|---|---|
| analytics_identifier | integer | false | An identifier which clients of the Publishing API can include with an edition for later use in analytics software. |
| base_path | string | true | The path of the content on GOV.UK - or the shortest one for content that spans multiple sub paths. Learn more. |
| content_id | string(uuid) | false | A UUID which represents the public identifier for a piece of content, combined with locale this makes the unique identifier for an individual piece of content. Can be null for redirects / gone content. |
| description | string | false | A description of the content which can then be displayed publically. |
| details | object | false | An object representing data that is structured in a format defined by the schema of the edition. This holds the content for the edition, often in a field called body. Can be null for items without content - for example, a redirect. Learn more. |
| document_type | string | true | A particular type of document, used to differentiate between documents that are of different types but share the same schema. Learn more. |
| email_document_supertype | string | true | High level group for email subscriptions used to identify publications and announcement. |
| first_published_at | string(date-time) | true | Can be set by publishing application, otherwise set automatically in Publishing API on first publish and copied on subsequent ones. |
| government_document_supertype | string | true | Grouping for email subscriptions. |
| links | object | true | An object that has collections of LinkedContentItems objects in arrays, which are grouped by a link type. |
| locale | string | false | The language the document is written in. A fixed list of locales is allowed. |
| navigation_document_supertype | string | true | Used to filter pages on the new taxonomy-based navigation pages. |
| phase | string | true | The "phase” of an edition can either be alpha, beta or live. |
| public_updated_at | string(date-time) | true | Can be set by publishing application, otherwise set automatically in Publishing API each time an edition is published with a major edition. |
| publishing_app | string | true | The application which published the edition. |
| publishing_request_id | string | false | The GOV.UK Request ID which was used when the content item was published. |
| rendering_app | string | false | The application which will be used to render the content of the edition. |
| schema_name | string | true | The name of the GOV.UK content schema that the request body will be validated against. Learn more. |
| title | string | false | The title of the edition, displayed to the user. |
| updated_at | string(date-time) | true | Current date time every time the content item changes, which could be an update to one of the dependent links. |
| user_journey_document_supertype | string | true | Used to distinguish pages used mainly for navigation (finding) from content pages (thing). |
| withdrawn_notice | WithdrawnNotice | false | If the edition is withdrawn, this will contain the information about when and why it was withdrawn. |
LinkedContentItem
A LinkedContentItem is an abridged form of ContentItem which is used to represent links between ContentItems.
It is embedded within the links field that is used within ContentItem and LinkedContentItem. Learn more.
Sample JSON
“`json { "api_path”: “/api/content/browse/tax/vat”, “base_path”: “/browse/tax/vat”, “content_id”: “895d337a-fa68-4c83-ab79-1c08016afe87”, “description”: “Includes online returns, rates, charging and record keeping”, “document_type”: “mainstream_browse_page”, “locale”: “en”, “public_updated_at”: “2015-06-24T13:56:39Z”, “schema_name”: “mainstream_browse_page”, “title”: “VAT”, “withdrawn”: false, “links”: {}, “api_url”: “https://www.gov.uk/api/content/browse/tax/vat”, “web_url”: “https://www.gov.uk/browse/tax/vat” } “`Fields
| Name | Type | Required | Description |
|---|---|---|---|
| analytics_identifier | integer | true | An identifier which clients of the Publishing API can include with an edition for later use in analytics software. |
| api_path | string | true | The base path of the content item, available from the API. |
| base_path | string | true | The path of the content on GOV.UK - or the shortest one for content that spans multiple sub paths. |
| content_id | string(uuid) | true | A UUID which represents the public identifier for a piece of content, combined with locale this makes the unique identifier for an individual piece of content. Can be null for redirects / gone content. |
| description | string | true | A description of the content which can then be displayed publically. |
| details | object | false | An object representing data that is structured in a format defined by the schema of the edition. This holds the content for the edition, often in a field called body. Can be null for items without content - for example, a redirect. |
| document_type | string | true | A particular type of document, used to differentiate between documents that are of different types but share the same schema. |
| links | object | true | An object that has collections of LinkedContentItems objects in arrays, which are grouped by a link type. |
| locale | string | true | The language the document is written in. A fixed list of locales is allowed. |
| public_updated_at | string(date-time) | true | Can be set by publishing application, otherwise set automatically in Publishing API each time an edition is published with a major edition. |
| schema_name | string | true | The name of the GOV.UK content schema that the request body will be validated against. |
| title | string | true | The title of the edition, displayed to the user. |
| withdrawn | boolean | true | Holds whether or not the content has been withdrawn. |
WithdrawnNotice
A WithdrawnNotice is an object that can be embedded within a ContentItem and is used to explain the reason a piece of content has been withdrawn. Learn more.
Sample JSON
”`json { “explanation”: “This guidance has been withdrawn from use because the Environment Agency no longer provides best practice guidance. See guidance on preventing harmful weeds and invasive non-native plants spreading weeds for information on controlling specific plants.
\nFields
| Name | Type | Required | Description |
|---|---|---|---|
| explanation | string | true | An explanation as to why the content was withdrawn. |
| withdrawn_at | string(date-time) | true | The date when the content was withdrawn. |