govuk-api
v1.2.0GOV.UK API Client
JavaScript API client for GOV.UK Content and Search APIs.
Contents
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 |