{"id":18369189,"url":"https://github.com/ideal-postcodes/paf-api","last_synced_at":"2025-06-25T00:05:14.263Z","repository":{"id":52376977,"uuid":"183231199","full_name":"ideal-postcodes/paf-api","owner":"ideal-postcodes","description":"HTTP service that parses Postcode Address File records into a correctly formatted address","archived":false,"fork":false,"pushed_at":"2021-04-30T08:39:33.000Z","size":2805,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-22T04:41:44.295Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ideal-postcodes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-24T13:08:54.000Z","updated_at":"2025-01-26T13:12:20.000Z","dependencies_parsed_at":"2022-08-31T20:02:23.984Z","dependency_job_id":null,"html_url":"https://github.com/ideal-postcodes/paf-api","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ideal-postcodes/paf-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fpaf-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fpaf-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fpaf-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fpaf-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ideal-postcodes","download_url":"https://codeload.github.com/ideal-postcodes/paf-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ideal-postcodes%2Fpaf-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261777470,"owners_count":23208120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T23:28:41.742Z","updated_at":"2025-06-25T00:05:14.246Z","avatar_url":"https://github.com/ideal-postcodes.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\r\n  \u003cimg src=\"https://img.ideal-postcodes.co.uk/PAF%20API%20Logo@3x.png\" alt=\"PAF API\"\u003e\r\n\u003c/h1\u003e\r\n\r\n\u003e HTTP API that parses Postcode Address File records into correctly formatted address lines\r\n\r\n![CI](https://github.com/ideal-postcodes/paf-api/workflows/CI/badge.svg)\r\n![Release](https://github.com/ideal-postcodes/paf-api/workflows/Release/badge.svg)\r\n[![Dependency Status](https://david-dm.org/ideal-postcodes/paf-api.png)](https://david-dm.org/ideal-postcodes/paf-api)\r\n[![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)\r\n[![npm version](https://badge.fury.io/js/paf-api.svg)](https://badge.fury.io/js/paf-api)\r\n[![install size](https://packagephobia.now.sh/badge?p=paf-api)](https://packagephobia.now.sh/result?p=paf-api)\r\n[![](https://images.microbadger.com/badges/image/idealpostcodes/paf-api.svg)](https://microbadger.com/images/idealpostcodes/paf-api)\r\n\r\n[![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)\r\n\r\nParses Postcode Address File records into correctly formatted address recognised by Royal Mail according to its Clear Addressing Guidelines.\r\n\r\nProduces consistent address lines, a post town line and a postcode line via HTTP\r\n\r\n## Features\r\n\r\n- Exposes [UK Clear Addressing](https://github.com/ideal-postcodes/uk-clear-addressing) as a HTTP service\r\n- Deployable as a docker container or node.js application\r\n\r\n![Correct Addressing](https://img.ideal-postcodes.co.uk/correct_address.gif)\r\n\r\n## Links\r\n\r\n- [GitHub Repository](https://github.com/ideal-postcodes/paf-api)\r\n- [Test Live on paf-api.ideal-postcodes.dev](https://paf-api.ideal-postcodes.dev)\r\n- [Docker Hub Image](https://hub.docker.com/r/idealpostcodes/paf-api)\r\n- [UK Clear Addressing Project](https://github.com/ideal-postcodes/uk-clear-addressing)\r\n- [NPM Package](https://www.npmjs.com/package/paf-api)\r\n- [More information on Postcode Address File data attributes](https://ideal-postcodes.co.uk/documentation/paf-data)\r\n- [PAF Programmer's Guide](https://js.ideal-postcodes.co.uk/guide.pdf)\r\n\r\n## Getting Started\r\n\r\nTry on [paf-api.ideal-postcodes.dev](https://paf-api.ideal-postcodes.dev)\r\n\r\n```bash\r\ncurl -X POST \\\r\n  https://paf-api.ideal-postcodes.dev/parse \\\r\n  -H 'Content-Type: application/json' \\\r\n  -d '{ \"sub_building_name\": \"Flat 8\", \"building_name\": \"Oxford House 110-114\", \"thoroughfare\": \"High Street\" }'\r\n```\r\n\r\n### HTTP API Usage\r\n\r\nThis API responds to `POST` requests to `/parse` with a JSON payload representing a PAF Record\r\n\r\n#### `POST /parse`\r\n\r\n##### Request\r\n\r\n```json\r\nPOST /parse\r\n\r\n{\r\n  \"postcode\": \"WS11 5SB\",\r\n  \"post_town\": \"CANNOCK\",\r\n  \"thoroughfare\": \"Pye Green Road\",\r\n  \"building_name\": \"Flower House 189A\",\r\n  \"organisation_name\": \"S D Alcott Florists\",\r\n}\r\n```\r\n\r\n##### Response\r\n\r\n```json\r\n{\r\n  \"query\": {\r\n    \"postcode\": \"WS11 5SB\",\r\n    \"post_town\": \"CANNOCK\",\r\n    \"thoroughfare\": \"Pye Green Road\",\r\n    \"building_name\": \"Flower House 189A\",\r\n    \"organisation_name\": \"S D Alcott Florists\",\r\n    \"building_number\": \"\",\r\n    \"sub_building_name\": \"\",\r\n    \"dependant_locality\": \"\",\r\n    \"double_dependant_locality\": \"\",\r\n    \"dependant_thoroughfare\": \"\",\r\n    \"po_box\": \"\",\r\n    \"department_name\": \"\",\r\n  },\r\n  \"formatted\": {\r\n    \"postcode\": \"WS11 5SB\",\r\n    \"post_town\": \"CANNOCK\",\r\n    \"line_1\": \"S D Alcott Florists\",\r\n    \"line_2\": \"Flower House\",\r\n    \"line_3\": \"189a Pye Green Road\",\r\n    \"premise\": \"Flower House, 189a\"\r\n  }\r\n}\r\n```\r\n\r\n#### Available Payload Attributes\r\n\r\n```javascript\r\n{\r\n  building_number: string | number;\r\n  building_name: string;\r\n  sub_building_name: string;\r\n  dependant_locality: string;\r\n  double_dependant_locality: string;\r\n  thoroughfare: string;\r\n  dependant_thoroughfare: string;\r\n  po_box: string;\r\n  post_town: string;\r\n  postcode: string;\r\n  department_name: string;\r\n  organisation_name: string;\r\n}\r\n```\r\n\r\n### Deploy\r\n\r\n#### Deploy as a docker container\r\n\r\nUsing the Docker CLI\r\n\r\n```\r\ndocker pull idealpostcodes/paf-api:latest\r\n\r\ndocker run -p 8080:8080 idealpostcodes/paf-api\r\n```\r\n\r\nAlternatively with `docker-compose`\r\n\r\n```bash\r\ngit clone https://github.com/ideal-postcodes/paf-api \u0026\u0026 cd paf-api\r\n\r\ndocker-compose up -d\r\n```\r\n\r\n#### Deploy as a Node.js process\r\n\r\nRequires Node.js 8 or above\r\n\r\n```bash\r\ngit clone https://github.com/ideal-postcodes/paf-api \u0026\u0026 cd paf-api \u0026\u0026 npm install\r\n\r\nnpm start # Traffic served on 8080\r\n```\r\n\r\n#### NPM Module\r\n\r\nThe npm module exports an Express app factory, which takes a `pino` logger\r\n\r\n```javascript\r\nconst { App } = require(\"paf-api\");\r\n\r\nconst app = App({ logger: pino() });\r\n\r\nhttp.createServer(app).listen(PORT);\r\n```\r\n\r\n#### Configuration\r\n\r\nThe following environment variables can be passed to the application.\r\n\r\n```bash\r\nPORT=8080 # Sets the port to listen on\r\n```\r\n\r\n## Licence\r\n\r\nMIT\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fpaf-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fideal-postcodes%2Fpaf-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fideal-postcodes%2Fpaf-api/lists"}