This is a quick start for working with GOV.UK's APIs

API Overview
Content API
Search API
- People
- Services
Organisations API
Governments API
Registers

API overview

To reuse content from GOV.UK you must meet the conditions of the Open Government Licence
Results are returned in JSON
Requests are unauthenticated
Please set an identifying user agent if you use it a lot. We'd like to talk to you about your needs!
https://www.gov.uk/help/reuse-govuk-content

Some people find it useful to use the GOV.UK browser extension to see behind the scenes when navigating around www.gov.uk.

Content API

This is the API that provides content for most pages on GOV.UK.

Take any page and insert /api/content between the domain and the path. It returns the JSON that we use to populate that page.

So for:

https://www.gov.uk/council-tax

You should get:

https://www.gov.uk/api/content/council-tax

Further docs: https://content-api.publishing.service.gov.uk/#gov-uk-content-api

Schemas

We have many different types of content on GOV.UK. The shape of the content returned from the API differs to meet the specific needs of each type.

They can reliably be expected to hold the following properties (with examples from https://gov.uk/council-tax):

{
  "base_path": "/council-tax",
  "content_id": "428c2bae-56c2-48bd-a917-3d04df0a63fd",
  "description": "Your Council Tax bill - how to work it out, who has to pay, discounts and exemptions",
  "document_type": "guide",
  "first_published_at": "2011-11-08T17:14:12.000+00:00",
  "locale": "en",
  "phase": "live",
  "public_updated_at": "2014-11-21T15:54:42.000+00:00",
  "publishing_app": "publisher",
  "publishing_scheduled_at": null,
  "rendering_app": "government-frontend",
  "scheduled_publishing_delay_seconds": null,
  "schema_name": "guide",
  "title": "Council Tax",
  "updated_at": "2019-08-16T23:53:02.920Z",
  "withdrawn_notice": {},
  "details": {},
  "links": {}
}

The details hash is where the information specific to that schema is stored. For /council-tax, it holds the html body for each page in the guide - guides are multiple html pages, but one item in the content API.

The links hash stores associations with other content, for example the organisations responsible for it, or related content that might appear in navigation.

I've removed them from this example because they make the page unwieldly to view, but you can see them by checking out the live content

Search API

This is the API that we use for searching on GOV.UK. It also allows us to provide dynamic content on pages like https://www.gov.uk/government/organisations/government-digital-service

Use it in conjunction with the Content API

The link field in any search result is its page path on GOV.UK.

Prefix it with https://gov.uk to open a web page
Prefix it with https://gov.uk/api/content to get the content API representation

Search with keywords

https://www.gov.uk/api/search.json?q=micropig

Paginate

https://www.gov.uk/api/search.json?q=tax&count=20&start=10

Gets 20 results starting at the tenth.

Order

Searches with keywords (the q parameter) are ordered by relevance by default.
Searches without keywords are ordered by "most viewed" over the last 14 days by default.
You can override this by using the order parameter.

https://www.gov.uk/api/search.json?q=tax&order=-public_timestamp

Allowed sort fields

Get only some fields

Do this to limit the response (and make it faster).

https://www.gov.uk/api/search.json?q=micropig&fields=title,description,link

Fields that are returned by default

Filter results by something

https://www.gov.uk/api/search.json?filter_organisations=hm-revenue-customs&fields=title&order=-public_timestamp

Only includes results from the hm-revenue-customs organisation.
Only includes the title (over the minimum)
Order by most recent to oldest

Aggregate / Facet / Group results

https://www.gov.uk/api/search.json?q=biscuit&facet_content_store_document_type=20,examples:2,example_scope:query,example_fields:title:description&count=5

Searches for biscuit
Groups the results by the content_store_document_type field
- Gets the first 20 content store document types
- Provides two examples of each
- The examples use the query too (they match the search for biscuit)
- Include title, description fields in the example
Also get 5 normal search results

Combine things

Find all the document type internal names:

https://www.gov.uk/api/search.json?facet_content_store_document_type=200&count=0

Use one to find all the docs of one type (step by step pages in this case):

https://www.gov.uk/api/search.json?filter_content_store_document_type=step_by_step_nav&count=50&fields=title,description,link

There may be more than 50 soon!

Find people

We're often asked about a people API. We don't have one yet, but you can find them by using variations on: https://www.gov.uk/api/search.json?filter_format=person&order=title

Find government services

This is a list of "start pages". These are landing pages for government services or tools. There are other places on the website that use the green start button pattern, but these are the "official" ones. https://www.gov.uk/api/search.json?filter_content_store_document_type=transaction&fields=link,title,description&count=500

Find step by step pages

These pages link together a set of guidance and services to help users complete end-to-end journeys, such as learning to drive a car. We implement the HowTo schema on these pages. https://www.gov.uk/api/search.json?filter_content_store_document_type=step_by_step_nav&count=100

Organisations API

Lists all organisations on GOV.UK including parent/child organisations and their current status.

https://www.gov.uk/api/organisations

Governments API

Lists all the governments back to https://www.gov.uk/api/governments/1801-to-1802-tory-government

https://www.gov.uk/api/governments

Registers

Check out https://www.registers.service.gov.uk/registers. It's not run by GOV.UK, so may have different terms and conditions to the above.

sihugh/GOV.UK API cheat sheet.md

Contents