Skip to main content

Application: finder-frontend

Serves finder and search pages for GOV.UK

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

Imported documents

Example pages rendered by finder-frontend


Finder frontend renders search on GOV.UK.

Live examples

Site search is available from the header of every page.

Site search screenshot

Finder pages

Finder pages provide facetted searching over a collection of documents.

Read more about how links-based facets are handled.

Finder frontend screenshot


  • Finder: Page containing a list of filterable documents and filters.
  • Facets: Metadata associated with documents.
  • Filters: Searchable/filterable metadata for example case_state={open|closed} for a CMA case.


Running the application

$ ./

You can optionally add the --live flag to use live search data.

If you are using the GDS development virtual machine then the application will be available on the host at

Running the test suite

Before you can run the test suite you’ll need the govuk-content-schemas repository locally. See lib/govuk_content_schema_examples.rb for more details.

The StandardJS JavaScript linter needs to be installed separately before running the default rake task. To make sure that it’s been installed run:

$ yarn install

The default rake task runs all the tests:

$ bundle exec rake

The application has Jasmine tests, which can be accessed at /specs when the application is running in development mode. These are also run when rake, above, is run.

To run the Jasmine tests separately: bundle exec cucumber

To run the JavaScript Jasmine tests separately: bundle exec rake jasmine:ci

Note: Running the JS tests require you to also install phantomjs with brew cask install phantomjs.

Making a new finder

  1. If required, add a schema to alphagov/search-api describing your document type – example
  2. Publish a Finder Content Item to the content store. See the doc for Finder Content Item for more info.
  3. Ensure your documents are indexed in alphagov/search-api correctly.

Developing a finder locally

You can run this application with a local file so you can develop a finder without having to publish the content item to the publishing-api.

For example:

DEVELOPMENT_FINDER_JSON=features/fixtures/aaib_reports_example.json ./ --live

How to add a fixed filter

You can use with the path of the page you looking for to migrate.

For example, you want to filter by the field link on /government/world/organisations You can access the following: You will be able to see inside results the field format

You can double check the filter by performing the following search using search-api:

For more information please refer to the search api documentation.

Application structure

  • No data store – all data comes via the APIs mentioned above.
  • app/models contains two kinds of object.
    1. Value objects used to wrap up responses from API calls.
    2. Facet objects which wrap up the behaviour of different types of facet – eg radios, selects, etc.
  • app/parsers contains objects which transform API responses into models.