GOV.UK API Client

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


Contents

- Getting started
- Examples
- Content API
- Search API

Getting started

$3

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

`javascript
// 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);
`

`bash
node index.js
`

$3

`html


`

Examples

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

Content API

Implements the GOV.UK Content API.

$3

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

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

#### Getting data from event

`javascript
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

$3

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

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

$3

Get first page of search items for a query

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

#### Getting data from resolved promise

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

#### Getting data from event

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

$3

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

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

#### Getting data from event

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

$3

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

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

$3

Get total amount of search items for a query.

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

#### Getting total from resolved promise

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

$3

Get facets for a field.

| Parameter | Type | Required |
| --------- | -------- | -------- |
| field | string | true |

#### Getting facets from resolved promise

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

$3

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 |