Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ideal-postcodes/core-node
Node.js client for api.ideal-postcodes.co.uk
https://github.com/ideal-postcodes/core-node
Last synced: 10 days ago
JSON representation
Node.js client for api.ideal-postcodes.co.uk
- Host: GitHub
- URL: https://github.com/ideal-postcodes/core-node
- Owner: ideal-postcodes
- License: mit
- Created: 2019-06-04T15:01:16.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T03:53:07.000Z (over 1 year ago)
- Last Synced: 2024-10-25T06:11:05.303Z (22 days ago)
- Language: TypeScript
- Homepage:
- Size: 1.87 MB
- Stars: 0
- Watchers: 6
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
> Node.js client for api.ideal-postcodes.co.uk
[](https://codecov.io/gh/ideal-postcodes/core-node)
[](https://david-dm.org/ideal-postcodes/core-node)
[](https://www.npmjs.com/package/@ideal-postcodes/core-node)
[](https://packagephobia.now.sh/result?p=@ideal-postcodes/core-node)
[](https://github.com/ideal-postcodes/core-node/actions)
`@ideal-postcodes/core-node` is the Node.js 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.dev](https://core-interface.ideal-postcodes.dev).
`@ideal-postcodes/core-node` is tested against [all maintained, stable releases](https://nodejs.org/en/about/releases/).
## 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.dev/#documentation)
- [npm Module](https://www.npmjs.com/package/@ideal-postcodes/core-node)
- [GitHub Repository](https://github.com/ideal-postcodes/core-node)
## Other JavaScript Clients
- [Browser Client Repository](https://github.com/ideal-postcodes/core-browser)
- [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)
- [Configure Agent](#configure-http-agent)
- [Proxy HTTP Requests](#proxy-requests)
#### Install
```bash
npm install @ideal-postcodes/core-node
```
#### Instantiate
```javascript
const { Client } = require("@ideal-postcodes/core-node");
// or, if applicable,
import { Client } from "@ideal-postcodes/core-node"
const client = new Client({ api_key: "iddqd" });
```
[Configuration options](https://core-interface.ideal-postcodes.dev/interfaces/client.config)
#### Use
```javascript
import { lookupPostcode } from "@ideal-postcodes/core-node";
const addresses = await lookupPostcode({ client, postcode: "SW1A2AA" });
```
#### Catch Errors
```javascript
import { lookupAddress, errors } from "@ideal-postcodes/core-node";
try {
await lookupAddress({ client, query: "10 downing street" });
} catch (error) {
if (error instanceof errors.IdpcRequestFailedError) {
// IdpcRequestFailedError indicates a 402 response code
// Possibly the key balance has been depleted
}
}
```
#### Configure HTTP Agent
`core-node` uses [got](https://github.com/sindresorhus/got) as its underlying HTTP client. The Ideal Postcodes API client can also be optionally configured with a [got](https://github.com/sindresorhus/got) options object which is fed to [got](https://github.com/sindresorhus/got) on every request.
Be aware this options object will overwrite any existing [got](https://github.com/sindresorhus/got) HTTP request parameters.
```javascript
const client = new Client({ api_key: "iddqd" }, {
cache: new Map, // Instantiate a cache: https://github.com/sindresorhus/got#cache-1
hooks: { // Hook into HTTP responses: https://github.com/sindresorhus/got#hooksafterresponse
afterResponse: response => {
modify(response);
log(response);
return response;
}
},
});
```
##### Proxy HTTP Requests
You can [proxy requests](https://github.com/sindresorhus/got#proxies) by configuring the underlying [got](https://github.com/sindresorhus/got) HTTP client.
```javascript
const tunnel = require("tunnel");
const client = new Client(config, {
agent: tunnel.httpOverHttp({
proxy: {
host: "localhost"
}
})
});
```
---
### 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.dev/#documentation)
#### Lookup a Postcode
Return addresses associated with a given `postcode`
```javascript
import { lookupPostcode } from "@ideal-postcodes/core-node";
const postcode = "id11qd";
const addresses = await lookupPostcode({ client, postcode });
```
[Method options](https://core-interface.ideal-postcodes.dev/interfaces/helper_methods.lookuppostcodeoptions)
#### Search for an Address
Return addresses associated with a given `query`
```javascript
import { lookupAddress } from "@ideal-postcodes/core-node";
const query = "10 downing street sw1a";
const addresses = await lookupAddress({ client, query });
```
[Method options](https://core-interface.ideal-postcodes.dev/interfaces/helper_methods.lookupaddressoptions)
#### Search for an Address by UDPRN
Return address for a given `udprn`
Invalid UDPRN will return `null`
```javascript
import { lookupUdprn } from "@ideal-postcodes/core-node";
const udprn = 23747771;
const address = await lookupUdprn({ client, udprn });
```
[Method options](https://core-interface.ideal-postcodes.dev/interfaces/helper_methods.lookupudprnoptions)
## Test
```bash
npm test
```
## Licence
MIT