PHPackages suilven/ukpostcodes - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. suilven/ukpostcodes ActiveLibrary[Utility & Helpers](/categories/utility) suilven/ukpostcodes =================== Wrapper around postcodes.io to get info about UK postcodes 1.0.0(6y ago)116[1 issues](https://github.com/gordonbanderson/ukpostcodes/issues)MITPHPCI failing Since May 10Pushed 6y ago1 watchersCompare [ Source](https://github.com/gordonbanderson/ukpostcodes)[ Packagist](https://packagist.org/packages/suilven/ukpostcodes)[ RSS](/packages/suilven-ukpostcodes/feed)WikiDiscussions master Synced today READMEChangelogDependencies (8)Versions (2)Used By (0) UK Postcodes API Wrapper ======================== [](#uk-postcodes-api-wrapper) [![Build Status](https://camo.githubusercontent.com/d57883c73c0562457ff5e5125e5f5795e29b9864504a5687cfb581f8e9860aa2/68747470733a2f2f7472617669732d63692e6f72672f676f72646f6e62616e646572736f6e2f756b706f7374636f6465732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/gordonbanderson/ukpostcodes)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/b39bc92995882bf408a105a76c792ec6f06087924653d0d0c04f5a2c08e0ccd9/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f676f72646f6e62616e646572736f6e2f756b706f7374636f6465732f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/gordonbanderson/ukpostcodes/?branch=master)[![codecov.io](https://camo.githubusercontent.com/00e7647dd5d28c0615d97208a3f332a8f7616deabc4f7341eb8923c7a1b31a6f/68747470733a2f2f636f6465636f762e696f2f6769746875622f676f72646f6e62616e646572736f6e2f756b706f7374636f6465732f636f7665726167652e7376673f6272616e63683d6d6173746572)](https://codecov.io/github/gordonbanderson/ukpostcodes?branch=master) [![Latest Stable Version](https://camo.githubusercontent.com/3b46fc7ab8243290c5019cc99462cbffc12c0215d442f0cfbe30bbf5581232e1/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f76657273696f6e)](https://packagist.org/packages/suilven/ukpostcodes)[![Latest Unstable Version](https://camo.githubusercontent.com/48c969c83570e010e5fd5c6ab89dfd1163a41fb5f6ab201f32c16aadc6ee030e/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f762f756e737461626c65)](//packagist.org/packages/suilven/ukpostcodes)[![Total Downloads](https://camo.githubusercontent.com/0ef3ffb65ef8ba60466e9f2d91564e48dd45686dbcb9d1e3b7411a807f8070ba/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f646f776e6c6f616473)](https://packagist.org/packages/suilven/ukpostcodes)[![License](https://camo.githubusercontent.com/7914102d2bd74b88e9325b6ca5bba52244cf05d4d292d42ef8c04c86141d8a64/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f6c6963656e7365)](https://packagist.org/packages/suilven/ukpostcodes)[![Monthly Downloads](https://camo.githubusercontent.com/699fc6f117d654799fa044078a8846566e39c24bc98a328dcd250f72d39d32a0/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f642f6d6f6e74686c79)](https://packagist.org/packages/suilven/ukpostcodes)[![Daily Downloads](https://camo.githubusercontent.com/d4c91e68d8e0438262f795a7462baf071f3df6be37c9f6c651bcb20b8db9a4b7/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f642f6461696c79)](https://packagist.org/packages/suilven/ukpostcodes)[![composer.lock](https://camo.githubusercontent.com/821b4e83f4b17f22df55363eaf54674d4744c17f0a29592d7dac20a2066eb87f/68747470733a2f2f706f7365722e707567782e6f72672f7375696c76656e2f756b706f7374636f6465732f636f6d706f7365726c6f636b)](https://packagist.org/packages/suilven/ukpostcodes) [![GitHub Code Size](https://camo.githubusercontent.com/29e523b8fae7d2f612ed200c0d62c93e0c30e98b2323918163b58e7eb372cb9b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f676f72646f6e62616e646572736f6e2f756b706f7374636f646573)](https://github.com/gordonbanderson/ukpostcodes)[![GitHub Repo Size](https://camo.githubusercontent.com/9848d59bf55e5a9f237c161e43856734e0958d51442f7a0a19682ead91ea6908/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f7265706f2d73697a652f676f72646f6e62616e646572736f6e2f756b706f7374636f646573)](https://github.com/gordonbanderson/ukpostcodes)[![GitHub Last Commit](https://camo.githubusercontent.com/329e96722b70dfdd58aa1617e82c2be1e6d8a1019a5a82e59822b7da86712636/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f676f72646f6e62616e646572736f6e2f756b706f7374636f646573)](https://github.com/gordonbanderson/ukpostcodes)[![GitHub Activity](https://camo.githubusercontent.com/41304e1a874301bf9b1acbbe669630a85fcd04bfb4981b6a3165e24ceeb5996c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6d6d69742d61637469766974792f6d2f676f72646f6e62616e646572736f6e2f756b706f7374636f646573)](https://github.com/gordonbanderson/ukpostcodes)[![GitHub Issues](https://camo.githubusercontent.com/042caec732b4f173d3e13a58a4acf1c28e0f6e6f1b48d07f9da4ca63b0b8955b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f676f72646f6e62616e646572736f6e2f756b706f7374636f646573)](https://github.com/gordonbanderson/ukpostcodes/issues) [![codecov.io](https://camo.githubusercontent.com/e169d5554f05a381a3d59b138dbfaa4756a967f51fb829406d02eb6002dc00f1/68747470733a2f2f636f6465636f762e696f2f6769746875622f676f72646f6e62616e646572736f6e2f756b706f7374636f6465732f6272616e63682e7376673f6272616e63683d6d6173746572)](https://camo.githubusercontent.com/e169d5554f05a381a3d59b138dbfaa4756a967f51fb829406d02eb6002dc00f1/68747470733a2f2f636f6465636f762e696f2f6769746875622f676f72646f6e62616e646572736f6e2f756b706f7374636f6465732f6272616e63682e7376673f6272616e63683d6d6173746572) PHP client wrapper around the postcodes.io API service [![dependency graph for clue/graph-composer](./packages/packages.svg)](./packages/packages.svg) Usage ===== [](#usage) Getting a PostCode ------------------ [](#getting-a-postcode) ``` $postcode = PostCodeFactory::get('KY16 9SS'); ``` or ``` $api = new Suilven\UKPostCodes\API(); $lookup = $this->api->lookup('KY16 9SS''); ``` Getting Nearby PostCodes ------------------------ [](#getting-nearby-postcodes) ``` $postcode = PostCodeFactory::get('KY16 9SS'); $nearby = $postcode->nearest(); ``` or ``` $api = new Suilven\UKPostCodes\API(); $nearest = $this->api->nearest('SW1A 2AA'); ``` Bulk Lookup By PostCode ----------------------- [](#bulk-lookup-by-postcode) ``` $api = new Suilven\UKPostCodes\API(); $postcodeObjects = $this->api->bulkLookup([ 'SW1A 2AA', 'KY16 9SS', 'KY11 3ED' ]); ``` Bulk Lookup By Coordinates -------------------------- [](#bulk-lookup-by-coordinates) ``` $api = new Suilven\UKPostCodes\API(); $coors = [ [ 'latitude' => 51.50354, 'longitude' => -0.127695, ], [ 'latitude' => 56.340349, 'longitude' => -2.808787, ], [ 'latitude' => 56.03587, 'longitude' => -3.500364, ], ]; $bulkReversed = $this->api->bulkReverseGeocoding($coors); ``` Bulk Lookup By Coordinates -------------------------- [](#bulk-lookup-by-coordinates-1) Note that if the coordinates are outside of the UK, an empty array is returned by the API. ``` $api = new Suilven\UKPostCodes\API(); $postcodeObjects = $this->api->nearestPostcodesFromLongLat(0.629834723775309, 51.7923246977375); ``` Lookup Up A Terminated PostCode ------------------------------- [](#lookup-up-a-terminated-postcode) Note that this will return a partially populated PostCode object. ``` $api = new Suilven\UKPostCodes\API(); $terminated = $this->api->lookupTerminated('AB1 0AA'); ``` Lookup an Outward Code ---------------------- [](#lookup-an-outward-code) An outcode is the part of a postcode prior to the space, e.g. `KY16` in `KY16 9SS` ``` $api = new Suilven\UKPostCodes\API(); $lookup = $this->api->lookupOutwardCode('RH1'); ``` Lookup Outward Code By Coordinates ---------------------------------- [](#lookup-outward-code-by-coordinates) ``` $api = new Suilven\UKPostCodes\API(); $lookup = $this->api->nearestOutwardCodeFromLongLat(0.629834723775309, 51.7923246977375); ``` Find the Nearest Outward Code to a Given Outward Code ----------------------------------------------------- [](#find-the-nearest-outward-code-to-a-given-outward-code) ``` $api = new Suilven\UKPostCodes\API(); $nearest = $this->api->nearestOutwardCode('RH1'); ``` Autocomplete a PostCode ----------------------- [](#autocomplete-a-postcode) ``` $api = new Suilven\UKPostCodes\API(); $autocompletedPostCodes = $this->api->partial('SW16'); ``` Query a Partial PostCode ------------------------ [](#query-a-partial-postcode) ``` $api = new Suilven\UKPostCodes\API(); $postcodeObjs = $this->api->query('SW16'); ``` Get a Random Postcode --------------------- [](#get-a-random-postcode) ``` $api = new Suilven\UKPostCodes\API(); $random = $this->api->random(); ``` Get Distance Between Two PostCodes ---------------------------------- [](#get-distance-between-two-postcodes) ``` $api = new Suilven\UKPostCodes\API(); $distance = $this->api->distance('SW1A 2AB', 'EH99 1SP', Distance::KM); ``` If the distance units parameter is not provided, then the default is miles (`MILES`). The other option is `NAUTICAL_MILES`. Check if a PostCode is Valid or Not ----------------------------------- [](#check-if-a-postcode-is-valid-or-not) ``` $api = new Suilven\UKPostCodes\API(); // false as there is no space in the postcode $validated = $this->api->validate('KYAB92A'); ``` Docker Dev Environment ====================== [](#docker-dev-environment) Starting -------- [](#starting) Note that the first time this is executed the container will be built. ``` sudo docker-compose up -d phpcli ``` Getting A Bash Prompt --------------------- [](#getting-a-bash-prompt) ``` sudo docker-compose exec phpcli /bin/bash ``` Running Tests Locally --------------------- [](#running-tests-locally) ``` root@ukpostcodes.dev:/var/www> vendor/bin/phpunit tests/ PHPUnit 7.5.20 by Sebastian Bergmann and contributors. .................................. 34 / 34 (100%) Time: 156 ms, Memory: 6.00 MB ``` Generating Test Coverage ------------------------ [](#generating-test-coverage) ``` phpdbg -qrr vendor/bin/phpunit -d memory_limit=4G --coverage-html report tests/ ``` ### Health Score 20 — LowBetter than 13% of packages Maintenance0 Infrequent updates — may be unmaintained Popularity7 Limited adoption so far Community7 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 2245d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/5550807?v=4)[suilven](/maintainers/suilven)[@suilven](https://github.com/suilven) --- Top Contributors [![gordonbanderson](https://avatars.githubusercontent.com/u/7060?v=4)](https://github.com/gordonbanderson "gordonbanderson (90 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/suilven-ukpostcodes/health.svg) ``` [![Health](https://phpackages.com/badges/suilven-ukpostcodes/health.svg)](https://phpackages.com/packages/suilven-ukpostcodes) ``` ### Alternatives [juvo/bricks-custom-query Easy to use custom bricks query 122.2k](/packages/juvo-bricks-custom-query) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)