{"id":20519831,"url":"https://github.com/jabranr/postcodes-io","last_synced_at":"2025-04-14T02:11:52.834Z","repository":{"id":56995345,"uuid":"74744011","full_name":"jabranr/postcodes-io","owner":"jabranr","description":"PHP library for postcodes.io","archived":false,"fork":false,"pushed_at":"2024-10-09T15:58:14.000Z","size":55,"stargazers_count":9,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T16:11:15.492Z","etag":null,"topics":["api","outcode","php-library","postcode"],"latest_commit_sha":null,"homepage":"https://postcodes-io/about","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/jabranr.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":"2016-11-25T09:26:38.000Z","updated_at":"2024-10-09T15:54:20.000Z","dependencies_parsed_at":"2022-08-21T10:40:43.980Z","dependency_job_id":null,"html_url":"https://github.com/jabranr/postcodes-io","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabranr%2Fpostcodes-io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabranr%2Fpostcodes-io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabranr%2Fpostcodes-io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabranr%2Fpostcodes-io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jabranr","download_url":"https://codeload.github.com/jabranr/postcodes-io/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248660083,"owners_count":21141238,"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":["api","outcode","php-library","postcode"],"created_at":"2024-11-15T22:16:31.969Z","updated_at":"2025-04-14T02:11:52.814Z","avatar_url":"https://github.com/jabranr.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostcodesIO [![Tests](https://github.com/jabranr/postcodes-io/actions/workflows/phpunit-tests.yml/badge.svg)](https://github.com/jabranr/postcodes-io/actions/workflows/phpunit-tests.yml) ![Packagist Version](https://img.shields.io/packagist/v/jabranr/postcodes-io?style=flat-square) ![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/jabranr/postcodes-io?style=flat-square)\n\nPostcodesIO is a PHP library for postcodes.io API.\n\n# Install\n\nInstall using composer:\n\n```\n$ composer require jabranr/postcodes-io\n```\n\n# Documentation\n\nAll of the following methods return back the same [complete response](https://postcodes.io/docs) as it comes from postcodes.io API in JSON format.\n\n# Development\n\n**Prerequisites**\n\n- Docker\n\n- Start container: `docker-compose up`\n- Run tests: `docker-compose exec postcodes_io bash -c \"composer test\"`\n\n**Debugging**\nXdebug is already installed and enabled as part of the docker setup. The project includes `launch.json` debug setup file for VSCode.\n\n#### Find postcode information\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n\ntry {\n  $addresses = $postcodesIO-\u003efind('NW1 5LD');\n} catch(\\Exception $e) {\n  echo $e-\u003egetMessage();\n}\n```\n\n\u003e You can catch specific `Jabranr\\PostcodesIO\\Exception\\PostcodeIOException` or/and catch general `\\Exception` to catch any type.\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO('NW1 5LD');\n$addresses = $postcodesIO-\u003egetResult();\n```\n\n#### Find postcode information by geo location\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003efindByLocation(51.520331, -0.1396267);\n```\n\n#### Find random postcode information\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003efindRandom();\n```\n\nOR use the alias method:\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003erandom();\n```\n\n#### Validate a postcode\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003evalidate('NW1 5LD');\n```\n\n#### Find nearest postcodes\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003efindNearest('NW1 5LD');\n```\n\nOR use the alias method:\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003enearest();\n```\n\n#### Get an autocompleted list of a postcode/outcode\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003eautocomplete('NW1');\n```\n\n#### Search a postcode\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003equery('NW1 5LD');\n```\n\nOR use the alias method:\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003esearch('NW1 5LD');\n```\n\n#### Find an outcode\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003efindOutcode('NW1');\n```\n\n#### Find nearest outcodes\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003enearestOutcode('NW1');\n```\n\n#### Find an outcode by location\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003efindOutcodeByLocation(51.520331, -0.1396267);\n```\n\n#### Bulk postcodes search\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003ebulkPostcodeSearch(array('NW1 5LD', 'W1T 7NY'));\n```\n\n\u003e Maximum of 100 postcodes per request.\n\n#### Bulk reverse geocoding\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003ebulkReverseGeocoding(array(\n    array(51.520331, -0.1396267),\n    array(51.520331, -0.1396267)\n));\n```\n\nor\n\n```php\nuse Jabranr\\PostcodesIO\\PostcodesIO;\n\n$postcodesIO = new PostcodesIO();\n$addresses = $postcodesIO-\u003ebulkReverseGeocoding(array(\n    array('latitude' =\u003e 51.520331, 'longitude' =\u003e -0.1396267),\n    array('latitude' =\u003e 51.520331, 'longitude' =\u003e -0.1396267)\n));\n```\n\n\u003e Maximum of 100 geolocations per request.\n\n# License\n\nMIT License\n\u0026copy; 2016 \u0026ndash; present | Jabran Rafique\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjabranr%2Fpostcodes-io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjabranr%2Fpostcodes-io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjabranr%2Fpostcodes-io/lists"}