PHPackages ammaar23/postcodes-io-sdk - 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. ammaar23/postcodes-io-sdk ActiveLibrary[Utility & Helpers](/categories/utility) ammaar23/postcodes-io-sdk ========================= A simple PHP sdk for Postcodes.io v1.1.2(7y ago)5836MITPHPPHP >=7.0 Since Apr 7Pushed 7y ago1 watchersCompare [ Source](https://github.com/ammaar23/postcodes-io-sdk)[ Packagist](https://packagist.org/packages/ammaar23/postcodes-io-sdk)[ Docs](https://github.com/ammaar23/postcodes-io-sdk)[ RSS](/packages/ammaar23-postcodes-io-sdk/feed)WikiDiscussions master Synced yesterday READMEChangelogDependencies (4)Versions (5)Used By (0) Postcodes.io PHP SDK [![Codacy Badge](https://camo.githubusercontent.com/37478d6ce53b08158d0b62f19b63ad8834c0041d153aaa70741010c062635ef0/68747470733a2f2f6170692e636f646163792e636f6d2f70726f6a6563742f62616467652f436f7665726167652f6636353039633333393239633433623262623637326430313061633631326439)](https://www.codacy.com/app/ammaar23/postcodes-io-sdk) [![Build Status](https://camo.githubusercontent.com/1c7fb1389ffe1806f5e3dfe8505c7fc5144fdb1fd26d5b3fcd59620d28e17385/68747470733a2f2f7472617669732d63692e6f72672f616d6d61617232332f706f7374636f6465732d696f2d73646b2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/ammaar23/postcodes-io-sdk) [![Latest Stable Version](https://camo.githubusercontent.com/e321ee1e92ce69e45f33c3c8bf88224ac11c0242ea278bcb6fe8c8d73e6f5156/68747470733a2f2f706f7365722e707567782e6f72672f616d6d61617232332f706f7374636f6465732d696f2d73646b2f762f737461626c652e737667)](https://packagist.org/packages/ammaar23/postcodes-io-sdk) [![Total Downloads](https://camo.githubusercontent.com/58ef2655fee99e2aa9947b94e6540f6ba9a9bfebbad9e9f77dded2116b760ddd/68747470733a2f2f706f7365722e707567782e6f72672f616d6d61617232332f706f7374636f6465732d696f2d73646b2f646f776e6c6f6164732e737667)](https://packagist.org/packages/ammaar23/postcodes-io-sdk) [![License](https://camo.githubusercontent.com/bea04a0aaee9b60aaa69de60cc07eb30ccb9bb480bccac9b0db3348608a065e4/68747470733a2f2f706f7365722e707567782e6f72672f616d6d61617232332f706f7374636f6465732d696f2d73646b2f6c6963656e73652e737667)](https://packagist.org/packages/ammaar23/postcodes-io-sdk) ==================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== [](#postcodesio-php-sdk-----) A simple PHP sdk for [Postcodes.io](https://postcodes.io) Install ------- [](#install) Install using composer: ``` $ composer require ammaar23/postcodes-io-sdk ``` Documentation ------------- [](#documentation) ### Basic Usage Example [](#basic-usage-example) ``` use Ammaar23\Postcodes\Postcode; use Ammaar23\Postcodes\PostcodeException; try { $postcodeService = new Postcode(); $response = $postcodeService->lookup('M60 2LA'); echo $response->admin_district; } catch(PostcodeException $e) { echo $e->getMessage(); } catch(\Exception $e) { echo $e->getMessage(); } ``` > You can catch specific `Ammaar23\Postcodes\PostcodeException` and/or catch general `\Exception` to catch any type. ### Add/Modify Configuration Parameters [](#addmodify-configuration-parameters) You can look at [Guzzle HTTP Request Options](http://docs.guzzlephp.org/en/stable/request-options.html) to find out the availabe options. ``` $postcodeService = new Postcode([ 'headers' => [ 'User-Agent' => 'testing/1.0', 'Accept' => 'application/json' ], 'timeout' => 2.0 ]); ``` ### Methods [](#methods) #### Lookup a postcode [](#lookup-a-postcode) Returns a single postcode entity for a given postcode (case, space insensitive). ``` // Definition function lookup(string $postcode): stdClass; // Example $postcodeService->lookup('M60 2LA'); ``` #### Bulk lookup postcodes [](#bulk-lookup-postcodes) Returns a list of matching postcodes and respective available data. ``` // Definition function lookupBulk(array $postcodes, array $attributes = []): array; // Examples $postcodeService->lookupBulk(['OX49 5NU', 'NE30 1DP']); $postcodeService->lookupBulk( ['OX49 5NU', 'NE30 1DP'], ['postcode', 'longitude', 'latitude'] ); ``` - `$attributes` (not required) is an array attributes to be returned in the result object(s). #### Reverse Geocoding [](#reverse-geocoding) Returns nearest postcodes for a given longitude and latitude. ``` // Definition function reverseGeocode(float $latitude, float $longitude, array $options = []): array; // Examples $postcodeService->reverseGeocode(51.7923246977375, 0.629834723775309); $postcodeService->reverseGeocode(51.7923246977375, 0.629834723775309, [ 'limit' => 5, 'radius' => 1000 ]); ``` - `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. - `radius` (not required) Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m. #### Bulk Reverse Geocoding [](#bulk-reverse-geocoding) Bulk translates geolocations into Postcodes. ``` // Definition function reverseGeocodeBulk(array $geolocations, array $attributes = [], int $wideSearch = null): array; // Examples $postcodeService->reverseGeocodeBulk([ ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309], ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5] ]); $postcodeService->reverseGeocodeBulk([ ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309], ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5] ], ['postcode', 'longitude', 'latitude']); $postcodeService->reverseGeocodeBulk([ ['latitude' => 51.7923246977375, 'longitude' => 0.629834723775309], ['latitude' => 53.5351312861402, 'longitude' => -2.49690382054704, 'radius' => 1000, 'limit' => 5] ], ['postcode', 'longitude', 'latitude'], 1000); ``` - Maximum of 100 geolocations per request. - `$attributes` (not required) is an array attributes to be returned in the result object(s). - `$wideSearch` (not required) Search up to 20km radius, but subject to a maximum of 10 results. #### Random Postcode [](#random-postcode) Returns a random postcode and all available data for that postcode. ``` // Definition function random(array $options = []): stdClass; // Examples $postcodeService->random(); $postcodeService->random([ 'outcode' => 'M60' ]); ``` - `outcode` (not required) Filters random postcodes by outcode. Returns null if invalid outcode. #### Validate a postcode [](#validate-a-postcode) Convenience method to validate a postcode. ``` // Definition function validate(string $postcode): bool; // Example $postcodeService->validate('M60 2LA'); ``` #### Validate a postcode format [](#validate-a-postcode-format) Convenience method to validate a postcode format. ``` // Definition function validateFormat(string $postcode): bool; // Example $postcodeService->validateFormat('M60 2LA'); ``` > `validateFormat` validates the format only where as `validate` check's if it exists in the Postcodes.io database or not. #### Nearest postcodes for postcode [](#nearest-postcodes-for-postcode) Returns nearest postcodes for a given postcode. ``` // Definition function nearest(string $postcode, array $options = []): array; // Examples $postcodeService->nearest('M60 2LA'); $postcodeService->nearest('M60 2LA', [ 'limit' => 5, 'radius' => 1000 ]); ``` - `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. - `radius` (not required) Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m. #### Autocomplete a postcode partial [](#autocomplete-a-postcode-partial) Convenience method to return an list of matching postcodes. ``` // Definition function autocomplete(string $postcode, array $options = []): array; // Examples $postcodeService->autocomplete('M60'); $postcodeService->autocomplete('M60', ['limit' => 5]); ``` - `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. #### Query for postcode [](#query-for-postcode) Submit a postcode query and receive a complete list of postcode matches and all associated postcode data. The result set can either be empty or populated with up to 100 postcode entities. ``` // Definition function query(string $query, array $options = []): array|null; // Examples $postcodeService->query('M60 2LA'); $postcodeService->query('M60 2LA', ['limit' => 5]); ``` - `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. Testing ------- [](#testing) ``` $ composer test ``` OR with coverage: ``` $ composer test-coverage ``` License ------- [](#license) MIT License © 2019 – [Ammaar Latif](https://twitter.com/ammaar23) ### Health Score 29 — LowBetter than 60% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity18 Limited adoption so far Community7 Small or concentrated contributor base Maturity58 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 Every ~1 days Total 4 Last Release 2590d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/295ce6602ad05dc3db5c73b2104678eff7f3a73ea2ef90ab8db33aacc78421c3?d=identicon)[ammaar23](/maintainers/ammaar23) --- Top Contributors [![ammaar23](https://avatars.githubusercontent.com/u/4119136?v=4)](https://github.com/ammaar23 "ammaar23 (13 commits)") --- Tags phpphp7postcodepostcode-validationpostcodeapisdk-phpphpsdkpackagepostcodespostcodes.io ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ammaar23-postcodes-io-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/ammaar23-postcodes-io-sdk/health.svg)](https://phpackages.com/packages/ammaar23-postcodes-io-sdk) ``` ### Alternatives [volcengine/volc-sdk-php Volcengine SDK for PHP 35113.0k4](/packages/volcengine-volc-sdk-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)