govuk-api

GOV.UK API Client

JavaScript API client for GOV.UK Content and Search APIs.

Contents

• Getting started
• Examples
• Content API
• Search API

Getting started

Node

npm init mjs -y # initialise module-ready package.json
npm install govuk-api

// index.js;
import { SearchAPI, ContentAPI } from "govuk-api";

const searchApi = new SearchAPI();
const contentApi = new ContentAPI();

const results = await searchApi.get("Keeping a pet pig");
// Find the first result that is closest...
const searchItem = results.find((item) => item.title.includes("micropig"));
const contentItem = await contentApi.get(searchItem.link);

console.log(contentItem);

node index.js

Browser

<!-- index.html -->
<script type="module">
  import { SearchAPI, ContentAPI } from "https://unpkg.com/govuk-api";

  const searchApi = new SearchAPI();
  const contentApi = new ContentAPI();

  const results = await searchApi.get("Keeping a pet pig");
  // Find the first result that is closest...
  const searchItem = results.find((item) => item.title.includes("micropig"));
  const contentItem = await contentApi.get(searchItem.link);

  console.log(contentItem);
</script>

Examples

• Streaming content items to json file
• Client-side browser Employment Tribunal Decision search (source)

Content API

Implements the GOV.UK Content API.

get(path)

Get a content item.

Parameter	Type	Required	Description
path	string	true	The path to the content on GOV.UK e.g for https://www.gov.uk/register-to-vote you’d use register-to-vote

Returns a content item from a promise or emitted by the 'data' event.

Getting data from resolved promise

import { ContentAPI } from "govuk-api";
const api = new ContentAPI();
const contentItem = await api.get("Register-to-vote");
console.log(contentItem);

Getting data from event

import { ContentAPI } from "govuk-api";
const api = new ContentAPI();
api.on("data", (contentItem) => {
  console.log(contentItem);
});
api.get("Register-to-vote");

Search API

Implements the GOV.UK Search API.

Use the search API to get useful information about GOV.UK content

constructor(queryOrOptions, [options])

Set the default query and options for all other calls to get, getAll and total methods

Parameter	Type	Required
queryOrOptions	string | Options	true
[options]	Options	false

Getting data from resolved promise

import { SearchAPI } from "govuk-api";
const api = new SearchAPI("Micro pig", { count: 10 });
const searchResults = await api.get();
console.log(searchResults);

get(queryOrOptions, [options])

Get first page of search items for a query

Parameter	Type	Required
queryOrOptions	string | Options	true
[options]	Options	false

Getting data from resolved promise

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
const searchResults = await api.get("Micro pig");
console.log(searchResults);

Getting data from event

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
api.on("data", (searchResults) => {
  console.log(searchResults);
});
api.get("Micro pig");

getAll(queryOrOptions, [options])

Get all pages of search items for a query.

Parameter	Type	Required	Description
queryOrOptions	string | Options	true
[options]	Options	false
options.total	number	false	maximum amount of results

Getting data from resolved promise

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
const searchResults = await api.getAll("Micro pig");
console.log(searchResults);

Getting data from event

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
api.on("data", (searchResults) => {
  console.log(searchResults);
});
api.getAll("Micro pig");

info(path)

Get metadata for a content item.

Parameter	Type	Required	Description
path	string	true	The path to the content on GOV.UK e.g for https://www.gov.uk/register-to-vote you’d use register-to-vote

Getting info from resolved promise

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
const contentInfo = await api.info("register-to-vote");
console.log(contentInfo);

total(queryOrOptions, [options])

Get total amount of search items for a query.

Parameter	Type	Required
queryOrOptions	string | Options	true
[options]	Options	false

Getting total from resolved promise

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
const totalResults = await api.total("Micro pig");
console.log(totalResults);

facets(field)

Get facets for a field.

Parameter	Type	Required
field	string	true

Getting facets from resolved promise

import { SearchAPI } from "govuk-api";
const api = new SearchAPI();
const facets = await api.facets("formats");
console.log(facets);

Options

You can use any options available in the Search API.

Name	Type	Description
q	string	search query

Pagination options

Name	Type	Description
start	number	position to start
count	number	number of results to return
order	string	sort order

Field options

Name	Type	Description
fields	Array	properties to return in search item

Faceted options

Name	Type	Description
filter.[field]	string	field to filter by
aggregate.[field]	string	field to aggregate by
reject.[field]	string	field to reject by
facet.[field]	string	group by field