Node.js client for api.ideal-postcodes.co.uk
@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.
High level client documentation can be found at core-interface.
In depth client documentation can be found at core-interface.ideal-postcodes.dev.
@ideal-postcodes/core-node is tested against all maintained, stable releases.
- Configuration & Usage
- Quickstart
- Client Documentation
- In Depth Client Documentation
- npm Module
- GitHub Repository
npm install @ideal-postcodes/core-nodeconst{ Client }=require("@ideal-postcodes/core-node");// or, if applicable,import{Client}from"@ideal-postcodes/core-node"constclient=newClient({api_key: "iddqd"});import{lookupPostcode}from"@ideal-postcodes/core-node";constaddresses=awaitlookupPostcode({ client,postcode: "SW1A2AA"});import{lookupAddress,errors}from"@ideal-postcodes/core-node";try{awaitlookupAddress({ client,query: "10 downing street"});}catch(error){if(errorinstanceoferrors.IdpcRequestFailedError){// IdpcRequestFailedError indicates a 402 response code// Possibly the key balance has been depleted}}core-node uses got as its underlying HTTP client. The Ideal Postcodes API client can also be optionally configured with a got options object which is fed to got on every request.
Be aware this options object will overwrite any existing got HTTP request parameters.
constclient=newClient({api_key: "iddqd"},{cache: newMap,// Instantiate a cache: https://github.com/sindresorhus/got#cache-1hooks: {// Hook into HTTP responses: https://github.com/sindresorhus/got#hooksafterresponseafterResponse: response=>{modify(response);log(response);returnresponse;}},});You can proxy requests by configuring the underlying got HTTP client.
consttunnel=require("tunnel");constclient=newClient(config,{agent: tunnel.httpOverHttp({proxy: {host: "localhost"}})});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.
For a complete list of client methods, including low level resource methods, please see the core-interface documentation
Return addresses associated with a given postcode
import{lookupPostcode}from"@ideal-postcodes/core-node";constpostcode="id11qd";constaddresses=awaitlookupPostcode({ client, postcode });Return addresses associated with a given query
import{lookupAddress}from"@ideal-postcodes/core-node";constquery="10 downing street sw1a";constaddresses=awaitlookupAddress({ client, query });Return address for a given udprn
Invalid UDPRN will return null
import{lookupUdprn}from"@ideal-postcodes/core-node";constudprn=23747771;constaddress=awaitlookupUdprn({ client, udprn });npm testMIT