Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ideal-postcodes/core-browser
JavaScript (browser) client for api.ideal-postcodes.co.uk
https://github.com/ideal-postcodes/core-browser
Last synced: 10 days ago
JSON representation
JavaScript (browser) client for api.ideal-postcodes.co.uk
- Host: GitHub
- URL: https://github.com/ideal-postcodes/core-browser
- Owner: ideal-postcodes
- Created: 2019-10-16T10:34:57.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-06T01:27:52.000Z (over 1 year ago)
- Last Synced: 2024-10-25T06:11:18.104Z (22 days ago)
- Language: TypeScript
- Homepage:
- Size: 9.02 MB
- Stars: 0
- Watchers: 6
- Forks: 0
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
> JavaScript (browser) client for api.ideal-postcodes.co.uk
[](https://github.com/ideal-postcodes/core-browser/actions/workflows/ci.yml)
[](https://codecov.io/gh/ideal-postcodes/core-browser)
[](https://david-dm.org/ideal-postcodes/core-browser)
[](https://badge.fury.io/js/%40ideal-postcodes%2Fcore-browser)
[](https://bundlephobia.com/result?p=@ideal-postcodes/core-browser)
[](https://github.com/ideal-postcodes/core-browser/actions)
`@ideal-postcodes/core-browser` is the JavaScript browser client for api.ideal-postcodes.co.uk
Our JavaScript client implements a common interface defined at [@ideal-postcodes/core-interface](https://github.com/ideal-postcodes/core-interface).
High level client documentation can be found at [core-interface](https://github.com/ideal-postcodes/core-interface/blob/master/README.md).
In depth client documentation can be found at [core-interface.ideal-postcodes.co.uk](https://core-interface.ideal-postcodes.co.uk).
Tested against [a suite of modern and legacy, mobile and desktop browsers](https://github.com/ideal-postcodes/supported-browsers).
`@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.
[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.
## Links
- [Configuration & Usage](#configuration--usage)
- [Quickstart](#quickstart)
- [Client Documentation](https://github.com/ideal-postcodes/core-interface/blob/master/README.md)
- [In Depth Client Documentation](https://core-interface.ideal-postcodes.co.uk/#documentation)
- [npm Module](https://www.npmjs.com/package/@ideal-postcodes/core-browser)
- [GitHub Repository](https://github.com/ideal-postcodes/core-browser)
## Other JavaScript Clients
- [Node.js Client Repository](https://github.com/ideal-postcodes/core-node)
- [Bundled Browser Client Repository](https://github.com/ideal-postcodes/core-browser-bundled)
- [Axios-backed Client Repository](https://github.com/ideal-postcodes/core-axios)
## Documentation
### Configuration & Usage
- [Install](#install)
- [Instantiate](#instantiate) and [Use](#use) client
- [Catch Errors](#catch-errors)
#### Install
```bash
npm install @ideal-postcodes/core-browser
```
#### Instantiate
```javascript
import { Client } from "@ideal-postcodes/core-browser";
const client = new Client({ api_key: "iddqd" });
```
[Configuration options](https://core-interface.ideal-postcodes.co.uk/interfaces/client.config)
#### Use
```javascript
const addresses = await lookupPostcode({ client: client, postcode: "SW1A2AA" });
```
#### Catch Errors
```javascript
import { errors } from "@ideal-postcodes/core-browser";
const { IdpcRequestFailedError } = errors;
try {
await lookupAddress({ client, query: "10 downing street" });
} catch (error) {
if (error instanceof IdpcRequestFailedError) {
// IdpcRequestFailedError indicates a 402 response code
// Possibly the key balance has been depleted
}
}
```
#### HTTP Agent and legacy browser support
`core-browser` uses the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) under the hood to facilitate HTTP requests.
A 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).
If 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).
---
### Quickstart
The 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.
- [Lookup a Postcode](#lookup-a-postcode)
- [Search for an Address](#search-for-an-address)
- [Search for an Address by UDPRN](#search-for-an-address-by-udprn)
For 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)
#### Lookup a Postcode
Return addresses associated with a given `postcode`
```javascript
const postcode = "id11qd";
const addresses = await lookupPostcode({ client, postcode });
```
[Method options](https://core-interface.ideal-postcodes.co.uk/interfaces/helper_methods.lookuppostcodeoptions)
#### Search for an Address
Return addresses associated with a given `query`
```javascript
const query = "10 downing street sw1a";
const addresses = await lookupAddress({ client, query });
```
[Method options](https://core-interface.ideal-postcodes.co.uk/interfaces/helper_methods.lookupaddressoptions)
#### Search for an Address by UDPRN
Return address for a given `udprn`
Invalid UDPRN will return `null`
```javascript
const udprn = 23747771;
const address = await lookupUdprn({ client, udprn });
```
[Method options](https://core-interface.ideal-postcodes.co.uk/interfaces/helper_methods.lookupudprnoptions)
## Test
```bash
npm test
```
## Licence
MIT