1 | <h1 align="center">
|
2 | <img src="https://img.ideal-postcodes.co.uk/Ideal%20Postcodes%20Axios%20Logo@3x.png" alt="Ideal Postcodes Axios">
|
3 | </h1>
|
4 |
|
5 | > Axios backed JavaScript client for api.ideal-postcodes.co.uk
|
6 |
|
7 | ![CI](https://github.com/ideal-postcodes/core-axios/workflows/CI/badge.svg)
|
8 | [![codecov](https://codecov.io/gh/ideal-postcodes/core-axios/branch/master/graph/badge.svg)](https://codecov.io/gh/ideal-postcodes/core-axios)
|
9 | [![Dependency Status](https://david-dm.org/ideal-postcodes/core-axios.svg)](https://david-dm.org/ideal-postcodes/core-axios)
|
10 | [![npm version](https://badge.fury.io/js/%40ideal-postcodes%2Fcore-axios.svg)](https://www.npmjs.com/package/@ideal-postcodes/core-axios)
|
11 | [![install size](https://packagephobia.now.sh/badge?p=@ideal-postcodes/core-axios)](https://packagephobia.now.sh/result?p=@ideal-postcodes/core-axios)
|
12 | [![Release](https://github.com/ideal-postcodes/core-axios/workflows/Release/badge.svg)](https://github.com/ideal-postcodes/core-axios/actions)
|
13 |
|
14 | `@ideal-postcodes/core-axios` is the Axios backed client for api.ideal-postcodes.co.uk. Axios is a promise based HTTP client for the browser and node.js and so is ideal for:
|
15 |
|
16 | - Frameworks that utilise server side rendering (Angular, Next.js, React, etc)
|
17 | - Isomorphic code (runs on browser and server)
|
18 |
|
19 | Our JavaScript client implements a common interface defined at [@ideal-postcodes/core-interface](https://github.com/ideal-postcodes/core-interface).
|
20 |
|
21 | High level client documentation can be found at [core-interface](https://github.com/ideal-postcodes/core-interface/blob/master/README.md).
|
22 |
|
23 | In depth client documentation can be found at [core-interface.ideal-postcodes.dev](https://core-interface.ideal-postcodes.dev).
|
24 |
|
25 | ## Links
|
26 |
|
27 | - [Configuration & Usage](#configuration--usage)
|
28 | - [Quickstart](#quickstart)
|
29 | - [Client Documentation](https://github.com/ideal-postcodes/core-interface/blob/master/README.md)
|
30 | - [In Depth Client Documentation](https://core-interface.ideal-postcodes.dev/#documentation)
|
31 | - [npm Module](https://www.npmjs.com/package/@ideal-postcodes/core-axios)
|
32 | - [GitHub Repository](https://github.com/ideal-postcodes/core-axios)
|
33 |
|
34 | ## Other JavaScript Clients
|
35 |
|
36 | - [Node.js Client Repository](https://github.com/ideal-postcodes/core-node)
|
37 | - [Browser Client Repository](https://github.com/ideal-postcodes/core-browser)
|
38 | - [Bundled Browser Client Repository](https://github.com/ideal-postcodes/core-browser-bundled)
|
39 |
|
40 | ## Documentation
|
41 |
|
42 | ### Configuration & Usage
|
43 |
|
44 | - [Install](#install)
|
45 | - [Instantiate](#instantiate) and [Use](#use) client
|
46 | - [Catch Errors](#catch-errors)
|
47 |
|
48 | #### Install
|
49 |
|
50 | ```bash
|
51 | npm install @ideal-postcodes/core-axios
|
52 | ```
|
53 |
|
54 | #### Instantiate
|
55 |
|
56 | ```javascript
|
57 | import { Client } from "@ideal-postcodes/core-axios"
|
58 |
|
59 | const client = new Client({ api_key: "iddqd" });
|
60 | ```
|
61 |
|
62 | [Configuration options](https://core-interface.ideal-postcodes.dev/interfaces/client.config)
|
63 |
|
64 | #### Use
|
65 |
|
66 | ```javascript
|
67 | import { lookupPostcode } from "@ideal-postcodes/core-axios"
|
68 |
|
69 | const addresses = await lookupPostcode({ client, postcode: "SW1A2AA" });
|
70 | ```
|
71 |
|
72 | #### Catch Errors
|
73 |
|
74 | ```javascript
|
75 | import { errors, lookupAddress } from "@ideal-postcodes/core-axios"
|
76 |
|
77 | try {
|
78 | await lookupAddress({ client, query: "10 downing street" });
|
79 | } catch (error) {
|
80 | if (error instanceof errors.IdpcRequestFailedError) {
|
81 | // IdpcRequestFailedError indicates a 402 response code
|
82 | // Possibly the key balance has been depleted
|
83 | }
|
84 | }
|
85 | ```
|
86 |
|
87 | ## Test
|
88 |
|
89 | ```bash
|
90 | npm test
|
91 | ```
|
92 |
|
93 | ## Licence
|
94 |
|
95 | MIT
|