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