{"id":24815480,"url":"https://github.com/ammaar23/postcodes-io-sdk","last_synced_at":"2025-10-13T17:31:43.846Z","repository":{"id":56947182,"uuid":"179982301","full_name":"ammaar23/postcodes-io-sdk","owner":"ammaar23","description":"A simple PHP sdk for Postcodes.io","archived":false,"fork":false,"pushed_at":"2019-04-10T01:46:51.000Z","size":53,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-15T06:52:05.147Z","etag":null,"topics":["php","php7","postcode","postcode-validation","postcodeapi","sdk-php"],"latest_commit_sha":null,"homepage":"https://postcodes.io","language":"PHP","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/ammaar23.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-07T15:04:14.000Z","updated_at":"2023-09-09T19:39:51.000Z","dependencies_parsed_at":"2022-08-21T03:10:26.804Z","dependency_job_id":null,"html_url":"https://github.com/ammaar23/postcodes-io-sdk","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ammaar23/postcodes-io-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaar23%2Fpostcodes-io-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaar23%2Fpostcodes-io-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaar23%2Fpostcodes-io-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaar23%2Fpostcodes-io-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ammaar23","download_url":"https://codeload.github.com/ammaar23/postcodes-io-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaar23%2Fpostcodes-io-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016290,"owners_count":26085828,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["php","php7","postcode","postcode-validation","postcodeapi","sdk-php"],"created_at":"2025-01-30T16:29:43.464Z","updated_at":"2025-10-13T17:31:43.567Z","avatar_url":"https://github.com/ammaar23.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Postcodes.io PHP SDK [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/f6509c33929c43b2bb672d010ac612d9)](https://www.codacy.com/app/ammaar23/postcodes-io-sdk) [![Build Status](https://travis-ci.org/ammaar23/postcodes-io-sdk.svg?branch=master)](https://travis-ci.org/ammaar23/postcodes-io-sdk) [![Latest Stable Version](https://poser.pugx.org/ammaar23/postcodes-io-sdk/v/stable.svg)](https://packagist.org/packages/ammaar23/postcodes-io-sdk) [![Total Downloads](https://poser.pugx.org/ammaar23/postcodes-io-sdk/downloads.svg)](https://packagist.org/packages/ammaar23/postcodes-io-sdk) [![License](https://poser.pugx.org/ammaar23/postcodes-io-sdk/license.svg)](https://packagist.org/packages/ammaar23/postcodes-io-sdk)\nA simple PHP sdk for [Postcodes.io](https://postcodes.io)\n\n## Install\n\nInstall using composer:\n\n```shell\n$ composer require ammaar23/postcodes-io-sdk\n```\n\n## Documentation\n\n### Basic Usage Example\n\n```php\nuse Ammaar23\\Postcodes\\Postcode;\nuse Ammaar23\\Postcodes\\PostcodeException;\n\ntry {\n    $postcodeService = new Postcode();\n    $response = $postcodeService-\u003elookup('M60 2LA');\n    echo $response-\u003eadmin_district;\n} catch(PostcodeException $e) {\n    echo $e-\u003egetMessage();\n} catch(\\Exception $e) {\n    echo $e-\u003egetMessage();\n}\n```\n\n\u003e You can catch specific `Ammaar23\\Postcodes\\PostcodeException` and/or catch general `\\Exception` to catch any type.\n\n### Add/Modify Configuration Parameters\n\nYou can look at [Guzzle HTTP Request Options](http://docs.guzzlephp.org/en/stable/request-options.html) to find out the availabe options.\n\n```php\n$postcodeService = new Postcode([\n    'headers' =\u003e [\n        'User-Agent' =\u003e 'testing/1.0',\n        'Accept' =\u003e 'application/json'\n    ],\n    'timeout' =\u003e 2.0\n]);\n```\n\n### Methods\n\n#### Lookup a postcode\n\nReturns a single postcode entity for a given postcode (case, space insensitive).\n\n```php\n// Definition\nfunction lookup(string $postcode): stdClass;\n\n// Example\n$postcodeService-\u003elookup('M60 2LA');\n```\n\n#### Bulk lookup postcodes\n\nReturns a list of matching postcodes and respective available data.\n\n```php\n// Definition\nfunction lookupBulk(array $postcodes, array $attributes = []): array;\n\n// Examples\n$postcodeService-\u003elookupBulk(['OX49 5NU', 'NE30 1DP']);\n$postcodeService-\u003elookupBulk(\n    ['OX49 5NU', 'NE30 1DP'],\n    ['postcode', 'longitude', 'latitude']\n);\n```\n\n* `$attributes` (not required) is an array attributes to be returned in the result object(s).\n\n#### Reverse Geocoding\n\nReturns nearest postcodes for a given longitude and latitude.\n\n```php\n// Definition\nfunction reverseGeocode(float $latitude, float $longitude, array $options = []): array;\n\n// Examples\n$postcodeService-\u003ereverseGeocode(51.7923246977375, 0.629834723775309);\n$postcodeService-\u003ereverseGeocode(51.7923246977375, 0.629834723775309, [\n    'limit' =\u003e 5,\n    'radius' =\u003e 1000\n]);\n```\n\n* `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.\n* `radius` (not required) Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m.\n\n#### Bulk Reverse Geocoding\n\nBulk translates geolocations into Postcodes.\n\n```php\n// Definition\nfunction reverseGeocodeBulk(array $geolocations, array $attributes = [], int $wideSearch = null): array;\n\n// Examples\n$postcodeService-\u003ereverseGeocodeBulk([\n    ['latitude' =\u003e 51.7923246977375, 'longitude' =\u003e 0.629834723775309],\n    ['latitude' =\u003e 53.5351312861402, 'longitude' =\u003e -2.49690382054704, 'radius' =\u003e 1000, 'limit' =\u003e 5]\n]);\n$postcodeService-\u003ereverseGeocodeBulk([\n    ['latitude' =\u003e 51.7923246977375, 'longitude' =\u003e 0.629834723775309],\n    ['latitude' =\u003e 53.5351312861402, 'longitude' =\u003e -2.49690382054704, 'radius' =\u003e 1000, 'limit' =\u003e 5]\n], ['postcode', 'longitude', 'latitude']);\n$postcodeService-\u003ereverseGeocodeBulk([\n    ['latitude' =\u003e 51.7923246977375, 'longitude' =\u003e 0.629834723775309],\n    ['latitude' =\u003e 53.5351312861402, 'longitude' =\u003e -2.49690382054704, 'radius' =\u003e 1000, 'limit' =\u003e 5]\n], ['postcode', 'longitude', 'latitude'], 1000);\n```\n\n* Maximum of 100 geolocations per request.\n* `$attributes` (not required) is an array attributes to be returned in the result object(s).\n* `$wideSearch` (not required) Search up to 20km radius, but subject to a maximum of 10 results.\n\n#### Random Postcode\n\nReturns a random postcode and all available data for that postcode.\n\n```php\n// Definition\nfunction random(array $options = []): stdClass;\n\n// Examples\n$postcodeService-\u003erandom();\n$postcodeService-\u003erandom([\n    'outcode' =\u003e 'M60'\n]);\n```\n\n* `outcode` (not required) Filters random postcodes by outcode. Returns null if invalid outcode.\n\n#### Validate a postcode\n\nConvenience method to validate a postcode.\n\n```php\n// Definition\nfunction validate(string $postcode): bool;\n\n// Example\n$postcodeService-\u003evalidate('M60 2LA');\n```\n\n#### Validate a postcode format\n\nConvenience method to validate a postcode format.\n\n```php\n// Definition\nfunction validateFormat(string $postcode): bool;\n\n// Example\n$postcodeService-\u003evalidateFormat('M60 2LA');\n```\n\n\u003e `validateFormat` validates the format only where as `validate` check's if it exists in the Postcodes.io database or not.\n\n#### Nearest postcodes for postcode\n\nReturns nearest postcodes for a given postcode.\n\n```php\n// Definition\nfunction nearest(string $postcode, array $options = []): array;\n\n// Examples\n$postcodeService-\u003enearest('M60 2LA');\n$postcodeService-\u003enearest('M60 2LA', [\n    'limit' =\u003e 5,\n    'radius' =\u003e 1000\n]);\n```\n\n* `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.\n* `radius` (not required) Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m.\n\n#### Autocomplete a postcode partial\n\nConvenience method to return an list of matching postcodes.\n\n```php\n// Definition\nfunction autocomplete(string $postcode, array $options = []): array;\n\n// Examples\n$postcodeService-\u003eautocomplete('M60');\n$postcodeService-\u003eautocomplete('M60', ['limit' =\u003e 5]);\n```\n\n* `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.\n\n#### Query for postcode\n\nSubmit 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.\n\n```php\n// Definition\nfunction query(string $query, array $options = []): array|null;\n\n// Examples\n$postcodeService-\u003equery('M60 2LA');\n$postcodeService-\u003equery('M60 2LA', ['limit' =\u003e 5]);\n```\n\n* `limit` (not required) Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100.\n\n## Testing\n\n```shell\n$ composer test\n```\n\nOR with coverage:\n\n```shell\n$ composer test-coverage\n```\n\n## License\nMIT License\n\u0026copy; 2019 \u0026ndash; [Ammaar Latif](https://twitter.com/ammaar23)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fammaar23%2Fpostcodes-io-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fammaar23%2Fpostcodes-io-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fammaar23%2Fpostcodes-io-sdk/lists"}