govuk v1.3.0

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.

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

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

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.

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.

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.

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.

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.

Pagination options

Field options

Faceted options