@ideal-postcodes/core-interface
Advanced tools
Interface specification for javascript based API Clients to api.ideal-postcodes.co.uk
JavaScript API for api.ideal-postcodes.co.uk
@ideal-postcodes/core-interface is an environment agnostic implementation of the Ideal Postcodes JavaScript API client interface.
If you are looking for the browser or Node.js client which implements this interface, please check out the downstream clients links.
To install, pick one of the following based on your platform
# For browser client
npm install @ideal-postcodes/core-browser
# For node.js client
npm install @ideal-postcodes/core-node
# For generic interface (you need to supply your own HTTP agent)
npm install @ideal-postcodes/core-interface
Instantiate a client with
import { Client } from "@ideal-postcodes/core-<package-type>";
const client = new Client({ api_key: "iddqd" });
// Only api_key is required by core-node and core-browser - all others are optional
// The agentless interface requires explicit configuration
The client exposes a number of simple methods to get at the most common tasks when interacting with the API
Return addresses associated with a given postcode
Invalid postcodes (i.e. postcode not found) return an empty array []
const postcode = "id11qd";
client.lookupPostcode({ postcode }).then(addresses => {
console.log(addresses);
{
postcode: "ID1 1QD",
line_1: "2 Barons Court Road",
// ...etc...
}
});
Return addresses associated with a given query
const query = "10 downing street sw1a";
client.lookupAddress({ query }).then(addresses => {
console.log(addresses);
{
postcode: "SW1A 2AA",
line_1: "Prime Minister & First Lord Of The Treasury",
// ...etc...
}
});
Return address for a given udprn
Invalid UDPRN will return null
const udprn = 23747771;
client.lookupUdprn({ udprn }).then(address => {
console.log(address);
{
postcode: "SW1A 2AA",
line_1: "Prime Minister & First Lord Of The Treasury",
// ...etc...
}
});
Return address for a given umprn
Invalid UMPRN will return null
const umprn = 50906066;
client.lookupUmprn({ umprn }).then(address => {
console.log(address);
{
postcode: "CV4 7AL",
line_1: "Room 1, Block 1 Arthur Vick",
// ...etc...
}
});
Check if a key is currently usable
client.checkKeyUsability({}).then(key => {
console.log(key.available); // => true
});
client.checkKeyUsability options
Resources defined in the API documentation are exposed on the client. Each resource exposes a method (#retrieve, #list, etc) which maps to a resource action.
These methods expose a low level interface to execute HTTP requests and observe HTTP responses. They are ideal if you have a more complex query or usecase where low level access would be useful.
Resource methods return a promise with a HTTP response object type.
Requesting a resource by ID (e.g. a postcode lookup for postcode with ID "SW1A 2AA") maps to the #retrieve method.
The first argument is the resource ID. The second argument is an object which accepts header and query attributes that map to HTTP header and the request querystring.
client.resourceName.retrieve("id", {
query: {
api_key: "foo",
tags: "this,that,those",
licensee: "sk_99dj3",
},
header: {
"IDPC-Source-IP": "8.8.8.8",
},
timeout: 5000,
});
Requesting a resource endpoint (e.g. an address query to /addresses) maps to the #list method.
client.resourceName.list({
query: {
api_key: "foo",
query: "10 downing street"
},
header: {
"IDPC-Source-IP": "8.8.8.8",
},
timeout: 5000,
});
The first and only argument is an object which accepts header and query attributes that map to HTTP header and the request querystring.
Some endpoints are defined as custom actions, e.g. /keys/:key/usage. These can be invoked using the name of the custom action.
E.g. for key usage data extraction
client.keys.usage(api_key, {
query: {
tags: "checkout,production"
},
header: {
Authorization: 'IDEALPOSTCODES user_token="foo"',
},
timeout: 5000,
});
Listed below are the available resources exposed by the client:
Retrieve addresses for a postcode.
client.postcodes.retrieve("SW1A2AA", {
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const addresses = response.body.result;
}).catch(error => logger(error));
Postcode resource HTTP API documentation
Search for an address
client.addresses.list({
query: {
query: "10 Downing street",
},
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const addresses = response.body.result.hits;
}).catch(error => logger(error));
Address resource HTTP API documentation
Autocomplete an address given an address partial
client.autocomplete.list({
query: {
query: "10 Downing stre",
},
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const suggestions = response.body.result.hits;
}).catch(error => logger(error));
Autocomplete resource HTTP API documentation
Autocomplete resource client docs
Retrieve an address given a UDPRN
client.udprn.retrieve("12345678", {
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const address = response.body.result;
}).catch(error => logger(error));
UDPRN resource HTTP API documentation
Retrieve a multiple residence premise given a UMPRN
client.umprn.retrieve("87654321", {
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const address = response.body.result;
}).catch(error => logger(error));
UMPRN resource HTTP API documentation
Find out if a key is available
client.keys.retrieve("iddqd", {})
.then(response => {
const { available } = response.body.result;
}).catch(error => logger(error));
Get private information on key (requires user_token)
client.keys.retrieve("iddqd", {
header: {
"Authorization": 'IDEALPOSTCODES user_token="secret-token"',
},
}).then(response => {
const key = response.body.result;
}).catch(error => logger(error));
Get key usage data
client.keys.usage("iddqd", {
header: {
"Authorization": 'IDEALPOSTCODES user_token="secret-token"',
},
}).then(response => {
const key = response.body.result;
}).catch(error => logger(error));
Keys resource HTTP API documentation
Client exports a static variable errors which contains custom error constructors that wrap specific API errors. These constructors can be used to test for specific cases using the instanceof operator.
For example:
const { IdpcInvalidKeyError } = Client.errors;
try {
const addresses = client.lookupPostcode({ postcode: "SW1A2AA" });
} catch (error) {
if (error instanceof IdpcInvalidKeyError) {
// Handle an invalid key error
}
}
Not all specific API errors will be caught. If a specific API error does not have an error constructor defined, a more generic error (determined by the HTTP status code) will be returned.
For example:
const { IdpcRequestFailedError } = Client.errors;
try {
const addresses = client.lookupPostcode({ postcode: "SW1A2AA" });
} catch (error) {
if (error instanceof IdpcRequestFailedError) {
// IdpcRequestFailedError indicates a 402 response code
// Possibly the key balance has been depleted
}
}
A sketch of the error prototype chain can be found here
For more advanced use cases, this core-interface library provides:
ErrorAside from inspecting the HTTP request status code and/or JSON body response codes, you may also test for specific error instances.
Errors that don't inherit from IdealPostcodesError would indicate some kind of error external to the API (e.g. bad network, request timeout).
import { errors } from "@ideal-postcodes/core-interface";
const { IdpcPostcodeNotFoundError } = errors;
// Handle a specific error
if (error instanceof IdpcPostcodeNotFoundError) {
// You got yourself an invalid API Key
}
// Alternatively use a switch statement
switch (true) {
case error instanceof IdpcPostcodeNotFoundError:
// You got yourself an invalid API Key
default:
// Default error handling path
}
All errors inherit from JavaScript's Error prototype.
Errors are grouped by HTTP status code classes.
Specific errors may be supplied for the following reasons:
Prototype Chain
# Parent class inherits from Javascript Error. Returned if no JSON Response body
IdealPostcodesError < Error
|
|- IdpcApiError # Generic Error Class, returned if JSON response body present
|
|- IdpcBadRequestError # 400 Errors
|- IdpcUnauthorisedError # 401 Errors
|- IdpcRequestFailedError # 402 Errors
| |- IdpcBalanceDepletedError
| |- IdpcLimitReachedError
|
|- IdpcResourceNotFoundError # 404 Errors
| |- IdpcPostcodeNotFoundError
| |- IdpcKeyNotFoundError
| |- IdpcUdprnNotFoundError
| |- IdpcUmprnNotFoundError
|
|- IdpcServerError # 500 Errors
The error parser consumes a HTTP API response and returns the correct error instance.
import { errors } from "@ideal-postcodes/core-interface";
const { parse, IdpcPostcodeNotFoundError } = errors;
const invalidPostcodeUrl = "https://api.ideal-postcodes.co.uk/v1/postcodes/bad_postcode?api_key=iddqd"
const response = await fetch(invalidPostcodeUrl);
// Generate an error object if present, otherwise returns `undefined`
const error = parse(response);
// Handle the error
if (error instanceof IdpcPostcodeNotFoundError) {...}
npm test
MIT
FAQs
Interface specification for javascript based API Clients to api.ideal-postcodes.co.uk
The npm package @ideal-postcodes/core-interface receives a total of 4,489 weekly downloads. As such, @ideal-postcodes/core-interface popularity was classified as popular.
We found that @ideal-postcodes/core-interface demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.