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

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

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";

  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";
const api = new ContentAPI();
const contentItem = await api.get("Register-to-vote");
console.log(contentItem);

Getting data from event

import { ContentAPI } from "govuk";
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";
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";
const api = new SearchAPI();
const searchResults = await api.get("Micro pig");
console.log(searchResults);

Getting data from event

import { SearchAPI } from "govuk";
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";
const api = new SearchAPI();
const searchResults = await api.getAll("Micro pig");
console.log(searchResults);

Getting data from event

import { SearchAPI } from "govuk";
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";
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";
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";
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 |