Skip to main content

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.

Servers

/{path}

get

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.

Parameters

ParameterInTypeRequiredDescription
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

Responses

StatusDescriptionSchema
200

A content item is available at that path.

{
  "analytics_identifier": "integer",
  "base_path": "string",
  "content_id": "string",
  "description": "string",
  "details": {},
  "document_type": "string",
  "email_document_supertype": "string",
  "first_published_at": "string",
  "government_document_supertype": "string",
  "links": {},
  "locale": "string",
  "navigation_document_supertype": "string",
  "phase": "string",
  "public_updated_at": "string",
  "publishing_app": "string",
  "publishing_request_id": "string",
  "rendering_app": "string",
  "schema_name": "string",
  "title": "string",
  "updated_at": "string",
  "user_journey_document_supertype": "string",
  "withdrawn_notice": {
    "explanation": "string",
    "withdrawn_at": "string"
  }
}
 ContentItem
303

A content item at a different location is responsible for the content at this path. Learn more.
404

No content item is available at that path.
410

The content item is no longer available at that path.

Schemas

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.

NameTypeRequiredDescriptionSchema
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 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 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 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 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 object false

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.

 WithdrawnNotice

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.

NameTypeRequiredDescriptionSchema
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 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 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.

NameTypeRequiredDescriptionSchema
explanation string true

An explanation as to why the content was withdrawn.
withdrawn_at string true

The date when the content was withdrawn.