Skip to main content
Last updated: 9 Feb 2026

GOV.UK Search: Introduction and overview

There are two common kinds of public-facing search service on GOV.UK: Site search and Finders.

In addition, there is also the publicly available https://www.gov.uk/api/search.json, powered by search-api. See Using the Search API for examples of how to use this. There is no equivalent publicly available endpoint for querying search-api-v2.

Site search is available on the GOV.UK homepage and from the blue super navigation header at the top of all gov.uk pages.

The url of site search is https://www.gov.uk/search/all which is rendered by finder frontend, and referred to in code as the all_content finder.

Search results for site search are usually provided by search-api-v2 and Google Vertex AI Search. Except in the following cases when site search falls back to using search-api

  1. When no search query is provided.
  2. When the query param use_v1=true is present, eg https://www.gov.uk/search/all?order=updated-newest&use_v1=true
  3. When a world_locations query param is present, eg https://www.gov.uk/search/all?order=updated-newest&world_locations=france

More information is available at GOV.UK Site search: How it works

Finders

Finders are search pages on GOV.UK that are configured to return only a subset of available search results scoped by document type. They are rendered by Finder Frontend, and their search results are provided by search-api.

Some examples:

  • https://www.gov.uk/search/news-and-communications
  • https://www.gov.uk/search/research-and-statistics
  • https://www.gov.uk/government/statistical-data-sets

All finder content items are configured and published from search-api, except for specialist finders which are published by specialist-publisher e.g. https://www.gov.uk/cma-cases (see configuration)

Documentation on how finder frontend queries the two search api applications is available at Finder Frontend: How search works

Search API versus Search API V2

search-api-v2 was built to improve the quality of search results for the majority of GOV.UK users (when compared with search-api) and retains a “minimally compatible” API with search-api. It uses Google Cloud Platform (GCP)‘s Vertex AI Search (“Discovery Engine”) product as its underlying search engine.

search-api uses an old version of Elasticsearch as its underlying search engine. There is currently no clear roadmap for retiring search-api.

How content gets into search

Content is published via Publishing API. After an edition is changed, Publishing API publishes a message to the published_documents topic exchange it configured on startup. Interested parties, such as search-api and search-api-v2, subscribe to this exchange to perform post-publishing actions.

search-api and search-api-v2 listen to the publishing queue using the govuk_message_queue_consumer gem. In search-api-v2, PublishingApiMessageProcessor processes the indexing of the content, whereas in search-api, the work is done by MessageProcessor.

In addition to GOV.UK content, GDS staff can insert “external links” into search via Search Admin.

Legacy means for getting content into search

search-api (v1) also has some 'legacy’ means of getting content into its indices. Whitehall makes some calls to Search API directly (typically for ‘non-editioned’ content), via Whitehall::SearchIndex, which is called by any model that includes the Searchable module. This legacy behaviour is recognised tech debt and is in the process of being removed.

Note that there shouldn’t be a situation where Whitehall submits content to Search API both directly and via Publishing API: the Search API’s ‘migrated formats’ file controls which document types Search API expects from each source. There’s a non_indexable section at the bottom that includes all of the Whitehall document types. Search API checks when processing messages from Publishing API whether or not the document type is indexable, and ignores them if it’s not.

Search api (v1) indices

search-api-v2 has no concept of an ‘index’, but search-api (v1) has multiple.

Documents are spread across two elasticsearch indices in Search API:

  • govuk: the index populated by Publishing API, intended to encapsulate all GOV.UK content
  • government - the remaining legacy ‘content index’, encapsulating some Whitehall content that is in the process of being migrated to the govuk index.

There are two Search API ADRs documenting the decision to move to one govuk index: ADR-04 and ADR-06. Some legacy indices (e.g. mainstream) have been fully migrated into it, but the legacy government index still remains.

One can find out which index a piece of content is saved under, using Search API’s API: see "index": "government" on this example.

In addition search-api stores best bets in the metasearch index, and popularity data in the page-traffic index.

Search Admin

The Search Admin application gives GDS staff a means of inserting “external links” into search. For example, searching for “Complain about bus services - Bus Users” surfaces a link to a non-GOV.UK URL.

As of March 2025, Search Admin is undergoing improvements. Watch this space!

Known limitations

More in the Search on GOV.UK section

Learn

How to...