{"id":15920944,"url":"https://github.com/nickcolley/govuk-api","last_synced_at":"2025-09-24T10:31:28.314Z","repository":{"id":62762001,"uuid":"562312476","full_name":"NickColley/govuk-api","owner":"NickColley","description":"JavaScript API client for GOV.UK Content and Search APIs.","archived":false,"fork":false,"pushed_at":"2023-05-12T13:24:23.000Z","size":300,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-14T06:22:27.204Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NickColley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-05T23:59:02.000Z","updated_at":"2024-04-23T04:25:57.000Z","dependencies_parsed_at":"2024-10-06T19:42:38.383Z","dependency_job_id":"d72df9ac-5a19-4339-999c-08fd61eeb55d","html_url":"https://github.com/NickColley/govuk-api","commit_stats":null,"previous_names":["nickcolley/govuk"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickColley%2Fgovuk-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickColley%2Fgovuk-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickColley%2Fgovuk-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickColley%2Fgovuk-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NickColley","download_url":"https://codeload.github.com/NickColley/govuk-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234072500,"owners_count":18774996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-06T19:42:22.092Z","updated_at":"2025-09-24T10:31:22.973Z","avatar_url":"https://github.com/NickColley.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GOV.UK API Client\n\nJavaScript API client for GOV.UK Content and Search APIs.\n\n[![GOVUK API latest npm version](https://img.shields.io/npm/v/govuk.svg?v=2)](https://www.npmjs.com/package/govuk)\n\n## Contents\n\n- [Getting started](#getting-started)\n- [Examples](#examples)\n- [Content API](#content-api)\n- [Search API](#search-api)\n\n## Getting started\n\n### Node\n\n```bash\nnpm init mjs -y # initialise module-ready package.json\nnpm install govuk\n```\n\n```javascript\n// index.js;\nimport { SearchAPI, ContentAPI } from \"govuk\";\n\nconst searchApi = new SearchAPI();\nconst contentApi = new ContentAPI();\n\nconst results = await searchApi.get(\"Keeping a pet pig\");\n// Find the first result that is closest...\nconst searchItem = results.find((item) =\u003e item.title.includes(\"micropig\"));\nconst contentItem = await contentApi.get(searchItem.link);\n\nconsole.log(contentItem);\n```\n\n```bash\nnode index.js\n```\n\n### Browser\n\n```html\n\u003c!-- index.html --\u003e\n\u003cscript type=\"module\"\u003e\n  import { SearchAPI, ContentAPI } from \"https://unpkg.com/govuk\";\n\n  const searchApi = new SearchAPI();\n  const contentApi = new ContentAPI();\n\n  const results = await searchApi.get(\"Keeping a pet pig\");\n  // Find the first result that is closest...\n  const searchItem = results.find((item) =\u003e item.title.includes(\"micropig\"));\n  const contentItem = await contentApi.get(searchItem.link);\n\n  console.log(contentItem);\n\u003c/script\u003e\n```\n\n## Examples\n\n- [Streaming content items to json file](./examples/streaming-content-to-json/index.js)\n- [Client-side browser Employment Tribunal Decision search](https://hello-govuk-api.glitch.me/) ([source](https://glitch.com/edit/#!/hello-govuk-api))\n\n## Content API\n\nImplements the [GOV.UK Content API](https://content-api.publishing.service.gov.uk).\n\n### get(path)\n\nGet a content item.\n\n| Parameter | Type   | Required | Description                                                                                                  |\n| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |\n| 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` |\n\nReturns a [content item](https://content-api.publishing.service.gov.uk/reference.html#contentitem) from a promise or emitted by the 'data' event.\n\n#### Getting data from resolved promise\n\n```javascript\nimport { ContentAPI } from \"govuk\";\nconst api = new ContentAPI();\nconst contentItem = await api.get(\"Register-to-vote\");\nconsole.log(contentItem);\n```\n\n#### Getting data from event\n\n```javascript\nimport { ContentAPI } from \"govuk\";\nconst api = new ContentAPI();\napi.on(\"data\", (contentItem) =\u003e {\n  console.log(contentItem);\n});\napi.get(\"Register-to-vote\");\n```\n\n## Search API\n\nImplements the [GOV.UK Search API](https://docs.publishing.service.gov.uk/repos/search-api/using-the-search-api.html).\n\n[Use the search API to get useful information about GOV.UK content](https://dataingovernment.blog.gov.uk/2016/05/26/use-the-search-api-to-get-useful-information-about-gov-uk-content/)\n\n### constructor(queryOrOptions, [options])\n\nSet the default query and options for all other calls to `get`, `getAll` and `total` methods\n\n| Parameter      | Type                              | Required |\n| -------------- | --------------------------------- | -------- |\n| queryOrOptions | `string` \\| [`Options`](#options) | true     |\n| [options]      | [`Options`](#options)             | false    |\n\n#### Getting data from resolved promise\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI(\"Micro pig\", { count: 10 });\nconst searchResults = await api.get();\nconsole.log(searchResults);\n```\n\n### get(queryOrOptions, [options])\n\nGet first page of search items for a query\n\n| Parameter      | Type                              | Required |\n| -------------- | --------------------------------- | -------- |\n| queryOrOptions | `string` \\| [`Options`](#options) | true     |\n| [options]      | [`Options`](#options)             | false    |\n\n#### Getting data from resolved promise\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\nconst searchResults = await api.get(\"Micro pig\");\nconsole.log(searchResults);\n```\n\n#### Getting data from event\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\napi.on(\"data\", (searchResults) =\u003e {\n  console.log(searchResults);\n});\napi.get(\"Micro pig\");\n```\n\n### getAll(queryOrOptions, [options])\n\nGet all pages of search items for a query.\n\n| Parameter      | Type                              | Required | Description               |\n| -------------- | --------------------------------- | -------- | ------------------------- |\n| queryOrOptions | `string` \\| [`Options`](#options) | true     |\n| [options]      | [`Options`](#options)             | false    |\n| options.total  | number                            | false    | maximum amount of results |\n\n#### Getting data from resolved promise\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\nconst searchResults = await api.getAll(\"Micro pig\");\nconsole.log(searchResults);\n```\n\n#### Getting data from event\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\napi.on(\"data\", (searchResults) =\u003e {\n  console.log(searchResults);\n});\napi.getAll(\"Micro pig\");\n```\n\n### info(path)\n\nGet metadata for a content item.\n\n| Parameter | Type     | Required | Description                                                                                                  |\n| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------ |\n| 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` |\n\n#### Getting info from resolved promise\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\nconst contentInfo = await api.info(\"register-to-vote\");\nconsole.log(contentInfo);\n```\n\n### total(queryOrOptions, [options])\n\nGet total amount of search items for a query.\n\n| Parameter      | Type                              | Required |\n| -------------- | --------------------------------- | -------- |\n| queryOrOptions | `string` \\| [`Options`](#options) | true     |\n| [options]      | [`Options`](#options)             | false    |\n\n#### Getting total from resolved promise\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\nconst totalResults = await api.total(\"Micro pig\");\nconsole.log(totalResults);\n```\n\n### facets(field)\n\nGet facets for a field.\n\n| Parameter | Type     | Required |\n| --------- | -------- | -------- |\n| field     | `string` | true     |\n\n#### Getting facets from resolved promise\n\n```javascript\nimport { SearchAPI } from \"govuk\";\nconst api = new SearchAPI();\nconst facets = await api.facets(\"formats\");\nconsole.log(facets);\n```\n\n### Options\n\n[You can use any options available in the Search API](https://docs.publishing.service.gov.uk/repos/search-api/using-the-search-api.html).\n\n| Name | Type     | Description  |\n| ---- | -------- | ------------ |\n| q    | `string` | search query |\n\n#### [Pagination options](https://docs.publishing.service.gov.uk/repos/search-api/using-the-search-api.html#pagination)\n\n| Name  | Type     | Description                 |\n| ----- | -------- | --------------------------- |\n| start | `number` | position to start           |\n| count | `number` | number of results to return |\n| order | `string` | sort order                  |\n\n#### [Field options](https://docs.publishing.service.gov.uk/repos/search-api/using-the-search-api.html#returning-specific-document-fields)\n\n| Name   | Type    | Description                         |\n| ------ | ------- | ----------------------------------- |\n| fields | `Array` | properties to return in search item |\n\n#### [Faceted options](https://docs.publishing.service.gov.uk/repos/search-api/public-api/faceted-search)\n\n| Name              | Type     | Description           |\n| ----------------- | -------- | --------------------- |\n| filter.[field]    | `string` | field to filter by    |\n| aggregate.[field] | `string` | field to aggregate by |\n| reject.[field]    | `string` | field to reject by    |\n| facet.[field]     | `string` | group by field        |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickcolley%2Fgovuk-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickcolley%2Fgovuk-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickcolley%2Fgovuk-api/lists"}