Skip to main content
Table of contents

Application: search-api

Search API for GOV.UK

AWS, on the search machine class
Continuously deployed?
Rake tasks
Integration, Staging or ⚠️ Production ⚠️

Relevant manual pages

Imported documents

Example pages published by search-api


Search API (née "rummager") indexes content into Elasticsearch and serves the GOV.UK Search API.

GOV.UK applications use the API to search and filter GOV.UK content. For example, alphagov/finder-frontend uses the search API to render site search and finder pages (such as

Search API also provides a public API:

Screenshot of API Response

API documentation

If you would like to use the Search API, please see the Search API documentation.

You can also find some examples in the blog post: "Use the search API to get useful information about GOV.UK content".

Getting started

The instructions will help you to get Search API running locally on your machine.


Install govuk-docker!

govuk-docker, a wrapper around docker-compose, is the supported way to run Search API and its dependencies locally.

Once you have installed govuk-docker, run

cd ~/govuk/govuk-docker && make search-api

Running the application

Once you have completed the prerequisites you'll be able to run Search API locally by running

cd ~/govuk/search-api && govuk-docker up search-api-app

This starts the Search API application and its dependencies.

The Search API will be running locally at

If you run docker ps this will tell you that there are containers running for Search API, Nginx, Redis, Publishing API, and Elasticsearch.

Note: If you're not using docker, you can run ./ to start the application. However, this is not officially supported, and you will need to run dependencies such as Elasticsearch and Redis yourself.

Replicating data locally

If you've started running Search API for the first time you probably aren't seeing any search results for your queries. That's likely because your local search indexes will be empty.

Once you have got everything running locally, another step most people take is to get a copy of the search indexes running locally. This will let you search for real documents on your local machine.

See the govuk-docker documentation on replicating data, or run

gds aws govuk-integration-poweruser ./bin/

Refer to the govuk-docker documentation for more details about the replication scripts.

Running the test suite

Complete the prerequisites, then run

govuk-docker run search-api-lite bundle exec rake

Note: You can also run the tests without using docker, by running bundle exec rake. This is not officially supported, but can be a quick way to run unit tests.

Technical documentation

Search API is a Sinatra application that interfaces with Elasticsearch.

Search API puts documents into Elasticsearch indexes (index time), and serves documents in search results (query time).

It does some clever stuff at both parts, but that's the meat of it.

Read the documentation to find out how documents are indexed or how documents are retrieved.


Search API depends on other services in order to index documents and provide relevant search results:

If you use govuk-docker locally, the required dependencies will be started automatically when you start Search API. You don't need to set these up yourself.

See the learning to rank documentation for guidance on how to run the ranking model locally.

Additional Docs


MIT License