1 | <h1 align="center">
|
2 | <img src="https://img.ideal-postcodes.co.uk/PAF%20API%20Logo@3x.png" alt="PAF API">
|
3 | </h1>
|
4 |
|
5 | > HTTP API that parses Postcode Address File records into correctly formatted address lines
|
6 |
|
7 | ![CI](https://github.com/ideal-postcodes/paf-api/workflows/CI/badge.svg)
|
8 | ![Release](https://github.com/ideal-postcodes/paf-api/workflows/Release/badge.svg)
|
9 | [![Dependency Status](https://david-dm.org/ideal-postcodes/paf-api.png)](https://david-dm.org/ideal-postcodes/paf-api)
|
10 | [![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/paf-api/badge.svg?branch=master)](https://coveralls.io/github/ideal-postcodes/paf-api?branch=master)
|
11 | [![npm version](https://badge.fury.io/js/paf-api.svg)](https://badge.fury.io/js/paf-api)
|
12 | [![install size](https://packagephobia.now.sh/badge?p=paf-api)](https://packagephobia.now.sh/result?p=paf-api)
|
13 | [![](https://images.microbadger.com/badges/image/idealpostcodes/paf-api.svg)](https://microbadger.com/images/idealpostcodes/paf-api)
|
14 |
|
15 | [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/ideal-postcodes/paf-api)
|
16 |
|
17 | Parses Postcode Address File records into correctly formatted address recognised by Royal Mail according to its Clear Addressing Guidelines.
|
18 |
|
19 | Produces consistent address lines, a post town line and a postcode line via HTTP
|
20 |
|
21 | ## Features
|
22 |
|
23 | - Exposes [UK Clear Addressing](https://github.com/ideal-postcodes/uk-clear-addressing) as a HTTP service
|
24 | - Deployable as a docker container or node.js application
|
25 |
|
26 | ![Correct Addressing](https://img.ideal-postcodes.co.uk/correct_address.gif)
|
27 |
|
28 | ## Links
|
29 |
|
30 | - [Github Repository](https://github.com/ideal-postcodes/paf-api)
|
31 | - [Test Live on paf-api.ideal-postcodes.dev](https://paf-api.ideal-postcodes.dev)
|
32 | - [Docker Hub Image](https://hub.docker.com/r/idealpostcodes/paf-api)
|
33 | - [UK Clear Addressing Project](https://github.com/ideal-postcodes/uk-clear-addressing)
|
34 | - [NPM Package](https://www.npmjs.com/package/paf-api)
|
35 | - [More information on Postcode Address File data attributes](https://ideal-postcodes.co.uk/documentation/paf-data)
|
36 | - [PAF Programmer's Guide](https://js.ideal-postcodes.co.uk/guide.pdf)
|
37 |
|
38 | ## Getting Started
|
39 |
|
40 | Try on [paf-api.ideal-postcodes.dev](https://paf-api.ideal-postcodes.dev)
|
41 |
|
42 | ```bash
|
43 | curl -X POST \
|
44 | https://paf-api.ideal-postcodes.dev/parse \
|
45 | -H 'Content-Type: application/json' \
|
46 | -d '{ "sub_building_name": "Flat 8", "building_name": "Oxford House 110-114", "thoroughfare": "High Street" }'
|
47 | ```
|
48 |
|
49 | ### HTTP API Usage
|
50 |
|
51 | This API responds to `POST` requests to `/parse` with a JSON payload representing a PAF Record
|
52 |
|
53 | #### `POST /parse`
|
54 |
|
55 | ##### Request
|
56 |
|
57 | ```json
|
58 | POST /parse
|
59 |
|
60 | {
|
61 | "postcode": "WS11 5SB",
|
62 | "post_town": "CANNOCK",
|
63 | "thoroughfare": "Pye Green Road",
|
64 | "building_name": "Flower House 189A",
|
65 | "organisation_name": "S D Alcott Florists",
|
66 | }
|
67 | ```
|
68 |
|
69 | ##### Response
|
70 |
|
71 | ```json
|
72 | {
|
73 | "query": {
|
74 | "postcode": "WS11 5SB",
|
75 | "post_town": "CANNOCK",
|
76 | "thoroughfare": "Pye Green Road",
|
77 | "building_name": "Flower House 189A",
|
78 | "organisation_name": "S D Alcott Florists",
|
79 | "building_number": "",
|
80 | "sub_building_name": "",
|
81 | "dependant_locality": "",
|
82 | "double_dependant_locality": "",
|
83 | "dependant_thoroughfare": "",
|
84 | "po_box": "",
|
85 | "department_name": "",
|
86 | },
|
87 | "formatted": {
|
88 | "postcode": "WS11 5SB",
|
89 | "post_town": "CANNOCK",
|
90 | "line_1": "S D Alcott Florists",
|
91 | "line_2": "Flower House",
|
92 | "line_3": "189a Pye Green Road",
|
93 | "premise": "Flower House, 189a"
|
94 | }
|
95 | }
|
96 | ```
|
97 |
|
98 | #### Available Payload Attributes
|
99 |
|
100 | ```javascript
|
101 | {
|
102 | building_number: string | number;
|
103 | building_name: string;
|
104 | sub_building_name: string;
|
105 | dependant_locality: string;
|
106 | double_dependant_locality: string;
|
107 | thoroughfare: string;
|
108 | dependant_thoroughfare: string;
|
109 | po_box: string;
|
110 | post_town: string;
|
111 | postcode: string;
|
112 | department_name: string;
|
113 | organisation_name: string;
|
114 | }
|
115 | ```
|
116 |
|
117 | ### Deploy
|
118 |
|
119 | #### Deploy as a docker container
|
120 |
|
121 | Using the docker CLI
|
122 |
|
123 | ```
|
124 | docker pull idealpostcodes/paf-api:latest
|
125 |
|
126 | docker run -p 8080:8080 idealpostcodes/paf-api
|
127 | ```
|
128 |
|
129 | Alternatively with docker-compose
|
130 |
|
131 | ```bash
|
132 | git clone https://github.com/ideal-postcodes/paf-api && cd paf-api
|
133 |
|
134 | docker-compose up -d
|
135 | ```
|
136 |
|
137 | #### Deploy as a node.js process
|
138 |
|
139 | Requires node.js 8 or above
|
140 |
|
141 | ```bash
|
142 | git clone https://github.com/ideal-postcodes/paf-api && cd paf-api && npm install
|
143 |
|
144 | npm start # Traffic served on 8080
|
145 | ```
|
146 |
|
147 | #### NPM Module
|
148 |
|
149 | The npm module exports an express app factory which takes a `pino` logger
|
150 |
|
151 | ```javascript
|
152 | const { App } = require("paf-api");
|
153 |
|
154 | const app = App({ logger: pino() });
|
155 |
|
156 | http.createServer(app).listen(PORT);
|
157 | ```
|
158 |
|
159 | #### Configuration
|
160 |
|
161 | The following environment variables can be passed to the application.
|
162 |
|
163 | ```bash
|
164 | PORT=8080 # Sets the port to listen on
|
165 | ```
|
166 |
|
167 | ## Licence
|
168 |
|
169 | MIT
|
170 |
|