{"id":18369183,"url":"https://github.com/ideal-postcodes/core-browser","last_synced_at":"2025-04-10T19:40:01.342Z","repository":{"id":35175655,"uuid":"215522112","full_name":"ideal-postcodes/core-browser","owner":"ideal-postcodes","description":"JavaScript (browser) client for api.ideal-postcodes.co.uk","archived":false,"fork":false,"pushed_at":"2023-03-06T01:27:52.000Z","size":9461,"stargazers_count":0,"open_issues_count":41,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T23:35:19.393Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ideal-postcodes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-10-16T10:34:57.000Z","updated_at":"2021-10-04T09:27:46.000Z","dependencies_parsed_at":"2024-11-05T23:30:44.649Z","dependency_job_id":"65c52fe5-90fe-4821-8d25-03679fc91722","html_url":"https://github.com/ideal-postcodes/core-browser","commit_stats":{"total_commits":892,"total_committers":8,"mean_commits":111.5,"dds":0.2600896860986547,"last_synced_commit":"9ac700241cfbab7eaf9aea6dff114c118eb54331"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fcore-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fcore-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fcore-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fcore-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ideal-postcodes","download_url":"https://codeload.github.com/ideal-postcodes/core-browser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247698480,"owners_count":20981358,"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-11-05T23:28:40.925Z","updated_at":"2025-04-10T19:40:01.316Z","avatar_url":"https://github.com/ideal-postcodes.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\r\n  \u003cimg src=\"https://img.ideal-postcodes.co.uk/Ideal%20Postcodes%20Browser%20Logo@3x.png\" alt=\"Ideal Postcodes Javascript Client\"\u003e\r\n\u003c/h1\u003e\r\n\r\n\u003e JavaScript (browser) client for api.ideal-postcodes.co.uk\r\n\r\n[![CI](https://github.com/ideal-postcodes/core-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/ideal-postcodes/core-browser/actions/workflows/ci.yml)\r\n![Cross Browser Testing](https://github.com/ideal-postcodes/core-browser/workflows/Cross%20Browser%20Testing/badge.svg?branch=saucelabs)\r\n[![codecov](https://codecov.io/gh/ideal-postcodes/core-browser/branch/master/graph/badge.svg?token=bjeFUcTPi5)](https://codecov.io/gh/ideal-postcodes/core-browser)\r\n[![Dependency Status](https://david-dm.org/ideal-postcodes/core-browser.svg)](https://david-dm.org/ideal-postcodes/core-browser)\r\n\r\n[![npm version](https://badge.fury.io/js/%40ideal-postcodes%2Fcore-browser.svg)](https://badge.fury.io/js/%40ideal-postcodes%2Fcore-browser)\r\n[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@ideal-postcodes/core-browser)](https://bundlephobia.com/result?p=@ideal-postcodes/core-browser)\r\n[![Release](https://github.com/ideal-postcodes/core-browser/workflows/Release/badge.svg)](https://github.com/ideal-postcodes/core-browser/actions)\r\n\r\n`@ideal-postcodes/core-browser` is the JavaScript browser client for api.ideal-postcodes.co.uk\r\n\r\nOur JavaScript client implements a common interface defined at [@ideal-postcodes/core-interface](https://github.com/ideal-postcodes/core-interface).\r\n\r\nHigh level client documentation can be found at [core-interface](https://github.com/ideal-postcodes/core-interface/blob/master/README.md).\r\n\r\nIn depth client documentation can be found at [core-interface.ideal-postcodes.co.uk](https://core-interface.ideal-postcodes.co.uk).\r\n\r\nTested against [a suite of modern and legacy, mobile and desktop browsers](https://github.com/ideal-postcodes/supported-browsers).\r\n\r\n`@ideal-postcodes/core-browser`should be consumed by a bundler or transpiler (e.g. webpack, parcel, rollup) for minification, module resolution and specific browser support.\r\n\r\n[core-browser-bundled](https://github.com/ideal-postcodes/core-browser-bundled) provides pre-bundled versions of `core-browser`, which can be immediately dropped into a page.\r\n\r\n## Links\r\n\r\n- [Configuration \u0026 Usage](#configuration--usage)\r\n- [Quickstart](#quickstart)\r\n- [Client Documentation](https://github.com/ideal-postcodes/core-interface/blob/master/README.md)\r\n- [In Depth Client Documentation](https://core-interface.ideal-postcodes.co.uk/#documentation)\r\n- [npm Module](https://www.npmjs.com/package/@ideal-postcodes/core-browser)\r\n- [GitHub Repository](https://github.com/ideal-postcodes/core-browser)\r\n\r\n## Other JavaScript Clients\r\n\r\n- [Node.js Client Repository](https://github.com/ideal-postcodes/core-node)\r\n- [Bundled Browser Client Repository](https://github.com/ideal-postcodes/core-browser-bundled)\r\n- [Axios-backed Client Repository](https://github.com/ideal-postcodes/core-axios)\r\n\r\n## Documentation\r\n\r\n### Configuration \u0026 Usage\r\n\r\n- [Install](#install)\r\n- [Instantiate](#instantiate) and [Use](#use) client\r\n- [Catch Errors](#catch-errors)\r\n\r\n#### Install\r\n\r\n```bash\r\nnpm install @ideal-postcodes/core-browser\r\n```\r\n\r\n#### Instantiate\r\n\r\n```javascript\r\nimport { Client } from \"@ideal-postcodes/core-browser\";\r\n\r\nconst client = new Client({ api_key: \"iddqd\" });\r\n```\r\n\r\n[Configuration options](https://core-interface.ideal-postcodes.co.uk/interfaces/client.config)\r\n\r\n#### Use\r\n\r\n```javascript\r\nconst addresses = await lookupPostcode({ client: client, postcode: \"SW1A2AA\" });\r\n```\r\n\r\n#### Catch Errors\r\n\r\n```javascript\r\nimport { errors } from \"@ideal-postcodes/core-browser\";\r\nconst { IdpcRequestFailedError } = errors;\r\n\r\ntry {\r\n  await lookupAddress({ client, query: \"10 downing street\" });\r\n} catch (error) {\r\n  if (error instanceof IdpcRequestFailedError) {\r\n    // IdpcRequestFailedError indicates a 402 response code\r\n    // Possibly the key balance has been depleted\r\n  }\r\n}\r\n```\r\n\r\n#### HTTP Agent and legacy browser support\r\n\r\n`core-browser` uses the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) under the hood to facilitate HTTP requests.\r\n\r\nA configuration object can be passed to the `Client` constructor as a second argument to override certain attributes on the [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request) of all subsequent fetch requests. Request configuration is documented [here](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).\r\n\r\nIf you need to [support older browsers](https://caniuse.com/#search=fetch), please include a [fetch polyfill](https://github.com/github/fetch) and transpile this library down to ES3. Alternatively use one of our pre-transpiled outputs at [ideal-postcodes/core-browser-bundled](https://github.com/ideal-postcodes/core-browser-bundled).\r\n\r\n---\r\n\r\n### Quickstart\r\n\r\nThe client exposes a number of simple methods to get at the most common tasks when interacting with the API. Below is a (incomplete) list of commonly used methods.\r\n\r\n- [Lookup a Postcode](#lookup-a-postcode)\r\n- [Search for an Address](#search-for-an-address)\r\n- [Search for an Address by UDPRN](#search-for-an-address-by-udprn)\r\n\r\nFor a complete list of client methods, including low level resource methods, please see the [core-interface documentation](https://core-interface.ideal-postcodes.co.uk/#documentation)\r\n\r\n#### Lookup a Postcode\r\n\r\nReturn addresses associated with a given `postcode`\r\n\r\n```javascript\r\nconst postcode = \"id11qd\";\r\n\r\nconst addresses = await lookupPostcode({ client, postcode });\r\n```\r\n\r\n[Method options](https://core-interface.ideal-postcodes.co.uk/interfaces/helper_methods.lookuppostcodeoptions)\r\n\r\n#### Search for an Address\r\n\r\nReturn addresses associated with a given `query`\r\n\r\n```javascript\r\nconst query = \"10 downing street sw1a\";\r\n\r\nconst addresses = await lookupAddress({ client, query });\r\n```\r\n\r\n[Method options](https://core-interface.ideal-postcodes.co.uk/interfaces/helper_methods.lookupaddressoptions)\r\n\r\n#### Search for an Address by UDPRN\r\n\r\nReturn address for a given `udprn`\r\n\r\nInvalid UDPRN will return `null`\r\n\r\n```javascript\r\nconst udprn = 23747771;\r\n\r\nconst address = await lookupUdprn({ client, udprn });\r\n```\r\n\r\n[Method options](https://core-interface.ideal-postcodes.co.uk/interfaces/helper_methods.lookupudprnoptions)\r\n\r\n## Test\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n## Licence\r\n\r\nMIT\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fcore-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fideal-postcodes%2Fcore-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fcore-browser/lists"}