{"id":15525147,"url":"https://github.com/antonioribeiro/zipcode","last_synced_at":"2025-04-06T16:13:32.197Z","repository":{"id":15946509,"uuid":"18688914","full_name":"antonioribeiro/zipcode","owner":"antonioribeiro","description":"Zip code searcher","archived":false,"fork":false,"pushed_at":"2021-02-24T15:22:51.000Z","size":134,"stargazers_count":98,"open_issues_count":16,"forks_count":41,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T15:08:16.028Z","etag":null,"topics":["android","laravel","php","zipcode"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antonioribeiro.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":"2014-04-11T21:13:14.000Z","updated_at":"2025-01-27T07:20:49.000Z","dependencies_parsed_at":"2022-08-30T19:10:37.813Z","dependency_job_id":null,"html_url":"https://github.com/antonioribeiro/zipcode","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonioribeiro%2Fzipcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonioribeiro%2Fzipcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonioribeiro%2Fzipcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonioribeiro%2Fzipcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antonioribeiro","download_url":"https://codeload.github.com/antonioribeiro/zipcode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509237,"owners_count":20950232,"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":["android","laravel","php","zipcode"],"created_at":"2024-10-02T10:55:06.030Z","updated_at":"2025-04-06T16:13:32.177Z","avatar_url":"https://github.com/antonioribeiro.png","language":"PHP","readme":"# ZipCode\r\n\r\n[![Latest Stable Version](https://poser.pugx.org/pragmarx/zipcode/v/stable.png)](https://packagist.org/packages/pragmarx/zipcode) [![License](https://poser.pugx.org/pragmarx/zipcode/license.png)](https://packagist.org/packages/pragmarx/zipcode)\r\n\r\n## A Laravel WorldWide ZIP code searcher\r\n\r\nYou can use it in Laravel:\r\n\r\n```php\r\nZipCode::setCountry('US');\r\n\r\nreturn Response::make(\r\n    ZipCode::find('10006')\r\n);\r\n```\r\n\r\nOr outside it:\r\n\r\n```php\r\n$z = new PragmaRX\\ZipCode\\ZipCode;\r\n\r\nreturn $z-\u003efind('20250030')-\u003etoArray();\r\n```\r\n\r\nIt automatically renders a JSON if you try to access it as string, but you still can:\r\n\r\n```php\r\n$result = ZipCode::find('10006');\r\n\r\n$json = $result-\u003etoJson();\r\n$array = $result-\u003etoArray();\r\n```\r\n\r\nSelect your preferred web service:\r\n\r\n```php\r\nZipCode::setPreferredWebService('Zippopotamus');\r\n```\r\n\r\nGet a web service by name, change things on it and find an address/city with it:\r\n\r\n```php\r\n$webService = ZipCode::getWebServiceByName('Zippopotamus');\r\n\r\n$webSerivice-\u003esetUrl('http://api.zippopotam.ca');\r\n\r\nreturn ZipCode::find('20250030', $webService);\r\n```\r\n\r\nCreate a new web service and add it to the list:\r\n\r\n```php\r\n$webService = new PragmaRX\\ZipCode\\Support\\WebService;\r\n\r\n$webSerivice-\u003esetUrl('http://api.zippopotam.ca');\r\n$webSerivice-\u003esetQuery('/%country%/%zip_code%');\r\n\r\nZipCode::addWebService($webService);\r\n```\r\n\r\nChange the user agent Guzzle will use to access the web service:\r\n\r\n```php\r\nZipCode::setUserAgent('Googlebot/2.1 (+http://www.google.com/bot.html)');\r\n```\r\n\r\nHow much time it took to find a zip?:\r\n\r\n```php\r\n$result = ZipCode::find('0200');\r\n\r\necho $result-\u003egetTimer();\r\n```\r\n\r\nGet a list of all available countries:\r\n\r\n```php\r\n$array = ZipCode::getAvailableCountries();\r\n```\r\n\r\nDynamically change query parameters, so if you have a [Geonames](http://www.geonames.org/) login, you can set it by doing:\r\n\r\n```php\r\nZipCode::setQueryParameter('geonames_username', 'yourusername');\r\n```\r\n\r\n## Web Services\r\n\r\nThis package uses web services all around the world to provide addresses and cities information. There are at least 2 web services available to all countries (Brazil currently has 6), if ZipCode cannot access one or doesn't find a zip on it, it automatically falls back to the others. If you know of any other web services available that could be better than those, please create an issue or PR with it.\r\n\r\n## Result\r\n\r\nThis is an example of what you get when you search a Zip with it:\r\n\r\n```javascript\r\n{\r\n   country_id:\"CH\",\r\n   country_name:\"Switzerland\",\r\n   zip_code:\"1005\",\r\n   web_service:\"Geonames\",\r\n   timer:\"0.7808\",\r\n   service_query_url:\"http://api.geonames.org/postalCodeSearch?country=CH\u0026postalcode=1005\u0026username=demo\",\r\n   addresses:[\r\n      {\r\n         postal_code:\"1005\",\r\n         state_name:\"Canton de Vaud\",\r\n         state_id:\"VD\",\r\n         city:\"Lausanne\",\r\n         latitude:\"46.51985\",\r\n         longitude:\"6.64252\",\r\n         department:\"District de Lausanne\",\r\n         department_id:\"2225\",\r\n         district:\"Lausanne\"\r\n      }\r\n   ],\r\n   result_raw:{\r\n      totalResultsCount:\"1\",\r\n      code:{\r\n         postalcode:\"1005\",\r\n         name:\"Lausanne\",\r\n         countryCode:\"CH\",\r\n         lat:\"46.51985\",\r\n         lng:\"6.64252\",\r\n         adminCode1:\"VD\",\r\n         adminName1:\"Canton de Vaud\",\r\n         adminCode2:\"2225\",\r\n         adminName2:\"District de Lausanne\",\r\n         adminCode3:\"5586\",\r\n         adminName3:\"Lausanne\"\r\n      }\r\n   },\r\n   success:true\r\n}\r\n```\r\n\r\nZipCode returns a `PragmaRX\\ZipCode\\Support\\Result` object and all properties can be accessed:\r\n\r\n* As array\r\n* As string, which will make it return a JSON\r\n* Using camel cased getters:\r\n\r\n```php\r\n$result-\u003egetWebService();\r\n$result-\u003egetCountryName();\r\n```\r\n\r\n## Laravel Form Example\r\n\r\nThis is an unconventionally hacked Laravel router which renders a form to query zips on a selected country:\r\n\r\n```php\r\nRoute::any('zipcode', function() {\r\n\r\n    echo\r\n        Form::open(array('url' =\u003e 'zipcode')) .\r\n        Form::select('country', ZipCode::getAvailableCountries(), Input::get('country')) .\r\n        Form::text('zipcode', Input::get('zipcode')) .\r\n        Form::submit('go!') .\r\n        Form::close();\r\n\r\n    if (Input::get('country'))\r\n    {\r\n        ZipCode::setCountry(Input::get('country'));\r\n\r\n        ZipCode::setQueryParameter('geonames_username', 'demo');\r\n\r\n        echo '\u003cpre\u003e';\r\n        var_dump(ZipCode::find(Input::get('zipcode'))-\u003etoArray());\r\n        echo '\u003c/pre\u003e';\r\n    }\r\n\r\n});\r\n```\r\n\r\n## Available countries\r\n\r\nThere are web services tested for the following countries:\r\n\r\n* Argentine (AR)\r\n* Australia (AU)\r\n* Brazil (BR)\r\n* Canada (CA)\r\n* Czech Republic (CZ)\r\n* France (FR)\r\n* Germany (DE)\r\n* Great Britain (GB)\r\n* India (IN)\r\n* Italy (IT)\r\n* Japan (JP)\r\n* Lithuania (LT)\r\n* Mexico (MX)\r\n* Pakistan (PK)\r\n* Poland (PL)\r\n* Portugal (PT)\r\n* Russia (RU)\r\n* South Africa (ZA)\r\n* Spain (ES)\r\n* Switzerland (CH)\r\n* Turkey (TR)\r\n* United States (US)\r\n\r\nIf you need a different one, please ask or just send a pull request with it.\r\n\r\n## Requirements\r\n\r\n- Laravel 4.1+ or 5+\r\n- PHP 5.4+\r\n\r\n## Installing\r\n\r\nInstall it using [Composer](https://getcomposer.org/doc/01-basic-usage.md):\r\n\r\n    composer require \"pragmarx/zipcode\"\r\n\r\nEdit your app/config/app.php and add the Service Provider\r\n\r\n    'PragmaRX\\ZipCode\\Vendor\\Laravel\\ServiceProvider',\r\n\r\nAnd the Facade\r\n\r\n    'ZipCode' =\u003e 'PragmaRX\\ZipCode\\Vendor\\Laravel\\Facade',\r\n\r\n## Using It\r\n\r\n#### Instantiate it directly\r\n\r\n```\r\nuse PragmaRX\\ZipCode\\ZipCode;\r\n\r\n$zipcode = new ZipCode();\r\n\r\nreturn $zipcode-\u003egenerateSecretKey()\r\n```\r\n\r\n#### In Laravel you can use the IoC Container and the contract\r\n\r\n```\r\n$zipcode = app()-\u003emake('PragmaRX\\ZipCode\\Contracts\\ZipCode');\r\n\r\nreturn $zipcode-\u003efind('20250-030')\r\n```\r\n\r\n#### Or Method Injection, in Laravel 5\r\n\r\n```\r\nuse PragmaRX\\ZipCode\\Contracts\\ZipCode;\r\n\r\nclass WelcomeController extends Controller {\r\n\r\n\tpublic function generateKey(ZipCode $zipcode)\r\n\t{\r\n\t\treturn $zipcode-\u003efind('20250-030');\r\n\t}\r\n\r\n}\r\n```\r\n\r\n## About Geonames\r\n\r\nThis is a really nice service and you should use it as your first option, but for it to be free (for 30,000 credits/day) you have to [create an user account](http://www.geonames.org/login) **and** [enable the free webservices](http://www.geonames.org/manageaccount). And configure ZipCode to use your username:\r\n\r\n```\r\nZipCode::setCountry('GB');\r\n\r\nZipCode::setQueryParameter('geonames_username', 'yourusername');\r\n\r\nZipCode::find('L23YL');\r\n```\r\n\r\nAnd you can also use config.php to set it:\r\n\r\n```\r\nreturn array(\r\n\r\n\t...\r\n\r\n\t'query_parameters' =\u003e array(\r\n\t\t'geonames_username' =\u003e 'demo',\r\n\t)\r\n\r\n);\r\n```\r\n\r\n## Author\r\n\r\n[Antonio Carlos Ribeiro](http://twitter.com/iantonioribeiro)\r\n\r\n## License\r\n\r\nZipCode is licensed under the BSD 3-Clause License - see the `LICENSE` file for details\r\n\r\n## Contributing\r\n\r\nPull requests and issues are more than welcome.\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonioribeiro%2Fzipcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonioribeiro%2Fzipcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonioribeiro%2Fzipcode/lists"}