PHPackages bee-b/zipcode - 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. bee-b/zipcode ActiveLibrary bee-b/zipcode ============= A worldwide address-by-zipcode searcher. v1.5.7(4y ago)011BSD-3-ClausePHP Since Apr 29Pushed 4y agoCompare [ Source](https://github.com/bee-b/zipcode)[ Packagist](https://packagist.org/packages/bee-b/zipcode)[ RSS](/packages/bee-b-zipcode/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (5)Versions (12)Used By (0) ZipCode ======= [](#zipcode) [![Latest Stable Version](https://camo.githubusercontent.com/fa974780287149613352abb7027ee2cff4940050b8a091186eff32b0c96880d2/68747470733a2f2f706f7365722e707567782e6f72672f707261676d6172782f7a6970636f64652f762f737461626c652e706e67)](https://packagist.org/packages/pragmarx/zipcode) [![License](https://camo.githubusercontent.com/c36ec0d974171e5abf8f9bc5f7451391feaaaf22ba60e8ef2d3388a3b807cc2d/68747470733a2f2f706f7365722e707567782e6f72672f707261676d6172782f7a6970636f64652f6c6963656e73652e706e67)](https://packagist.org/packages/pragmarx/zipcode) A Laravel WorldWide ZIP code searcher ------------------------------------- [](#a-laravel-worldwide-zip-code-searcher) You can use it in Laravel: ``` ZipCode::setCountry('US'); return Response::make( ZipCode::find('10006') ); ``` Or outside it: ``` $z = new PragmaRX\ZipCode\ZipCode; return $z->find('20250030')->toArray(); ``` It automatically renders a JSON if you try to access it as string, but you still can: ``` $result = ZipCode::find('10006'); $json = $result->toJson(); $array = $result->toArray(); ``` Select your preferred web service: ``` ZipCode::setPreferredWebService('Zippopotamus'); ``` Get a web service by name, change things on it and find an address/city with it: ``` $webService = ZipCode::getWebServiceByName('Zippopotamus'); $webSerivice->setUrl('http://api.zippopotam.ca'); return ZipCode::find('20250030', $webService); ``` Create a new web service and add it to the list: ``` $webService = new PragmaRX\ZipCode\Support\WebService; $webSerivice->setUrl('http://api.zippopotam.ca'); $webSerivice->setQuery('/%country%/%zip_code%'); ZipCode::addWebService($webService); ``` Change the user agent Guzzle will use to access the web service: ``` ZipCode::setUserAgent('Googlebot/2.1 (+http://www.google.com/bot.html)'); ``` How much time it took to find a zip?: ``` $result = ZipCode::find('0200'); echo $result->getTimer(); ``` Get a list of all available countries: ``` $array = ZipCode::getAvailableCountries(); ``` Dynamically change query parameters, so if you have a [Geonames](http://www.geonames.org/) login, you can set it by doing: ``` ZipCode::setQueryParameter('geonames_username', 'yourusername'); ``` Web Services ------------ [](#web-services) This 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. Result ------ [](#result) This is an example of what you get when you search a Zip with it: ``` { country_id:"CH", country_name:"Switzerland", zip_code:"1005", web_service:"Geonames", timer:"0.7808", service_query_url:"http://api.geonames.org/postalCodeSearch?country=CH&postalcode=1005&username=demo", addresses:[ { postal_code:"1005", state_name:"Canton de Vaud", state_id:"VD", city:"Lausanne", latitude:"46.51985", longitude:"6.64252", department:"District de Lausanne", department_id:"2225", district:"Lausanne" } ], result_raw:{ totalResultsCount:"1", code:{ postalcode:"1005", name:"Lausanne", countryCode:"CH", lat:"46.51985", lng:"6.64252", adminCode1:"VD", adminName1:"Canton de Vaud", adminCode2:"2225", adminName2:"District de Lausanne", adminCode3:"5586", adminName3:"Lausanne" } }, success:true } ``` ZipCode returns a `PragmaRX\ZipCode\Support\Result` object and all properties can be accessed: - As array - As string, which will make it return a JSON - Using camel cased getters: ``` $result->getWebService(); $result->getCountryName(); ``` Laravel Form Example -------------------- [](#laravel-form-example) This is an unconventionally hacked Laravel router which renders a form to query zips on a selected country: ``` Route::any('zipcode', function() { echo Form::open(array('url' => 'zipcode')) . Form::select('country', ZipCode::getAvailableCountries(), Input::get('country')) . Form::text('zipcode', Input::get('zipcode')) . Form::submit('go!') . Form::close(); if (Input::get('country')) { ZipCode::setCountry(Input::get('country')); ZipCode::setQueryParameter('geonames_username', 'demo'); echo ''; var_dump(ZipCode::find(Input::get('zipcode'))->toArray()); echo ''; } }); ``` Available countries ------------------- [](#available-countries) There are web services tested for the following countries: - Argentine (AR) - Australia (AU) - Brazil (BR) - Canada (CA) - Czech Republic (CZ) - France (FR) - Germany (DE) - Great Britain (GB) - India (IN) - Italy (IT) - Japan (JP) - Lithuania (LT) - Mexico (MX) - Pakistan (PK) - Poland (PL) - Portugal (PT) - Russia (RU) - South Africa (ZA) - Spain (ES) - Switzerland (CH) - Turkey (TR) - United States (US) If you need a different one, please ask or just send a pull request with it. Requirements ------------ [](#requirements) - Laravel 4.1+ or 5+ - PHP 5.4+ Installing ---------- [](#installing) Install it using [Composer](https://getcomposer.org/doc/01-basic-usage.md): ``` composer require "pragmarx/zipcode" ``` Edit your app/config/app.php and add the Service Provider ``` 'PragmaRX\ZipCode\Vendor\Laravel\ServiceProvider', ``` And the Facade ``` 'ZipCode' => 'PragmaRX\ZipCode\Vendor\Laravel\Facade', ``` Using It -------- [](#using-it) #### Instantiate it directly [](#instantiate-it-directly) ``` use PragmaRX\ZipCode\ZipCode; $zipcode = new ZipCode(); return $zipcode->generateSecretKey() ``` #### In Laravel you can use the IoC Container and the contract [](#in-laravel-you-can-use-the-ioc-container-and-the-contract) ``` $zipcode = app()->make('PragmaRX\ZipCode\Contracts\ZipCode'); return $zipcode->find('20250-030') ``` #### Or Method Injection, in Laravel 5 [](#or-method-injection-in-laravel-5) ``` use PragmaRX\ZipCode\Contracts\ZipCode; class WelcomeController extends Controller { public function generateKey(ZipCode $zipcode) { return $zipcode->find('20250-030'); } } ``` About Geonames -------------- [](#about-geonames) This 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: ``` ZipCode::setCountry('GB'); ZipCode::setQueryParameter('geonames_username', 'yourusername'); ZipCode::find('L23YL'); ``` And you can also use config.php to set it: ``` return array( ... 'query_parameters' => array( 'geonames_username' => 'demo', ) ); ``` Author ------ [](#author) [Antonio Carlos Ribeiro](http://twitter.com/iantonioribeiro) License ------- [](#license) ZipCode is licensed under the BSD 3-Clause License - see the `LICENSE` file for details Contributing ------------ [](#contributing) Pull requests and issues are more than welcome. ### Health Score 29 — LowBetter than 59% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity5 Limited adoption so far Community12 Small or concentrated contributor base Maturity70 Established project with proven stability Bus Factor1 Top contributor holds 93% 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 ~267 days Recently: every ~455 days Total 11 Last Release 1730d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/89344012?v=4)[bee-b](/maintainers/bee-b)[@bee-b](https://github.com/bee-b) --- Top Contributors [![antonioribeiro](https://avatars.githubusercontent.com/u/3182864?v=4)](https://github.com/antonioribeiro "antonioribeiro (119 commits)")[![bee-b](https://avatars.githubusercontent.com/u/89344012?v=4)](https://github.com/bee-b "bee-b (3 commits)")[![edward-rafalovsky](https://avatars.githubusercontent.com/u/17194690?v=4)](https://github.com/edward-rafalovsky "edward-rafalovsky (2 commits)")[![GlitterCakes](https://avatars.githubusercontent.com/u/5402396?v=4)](https://github.com/GlitterCakes "GlitterCakes (2 commits)")[![austenc](https://avatars.githubusercontent.com/u/575421?v=4)](https://github.com/austenc "austenc (1 commits)")[![bmartus](https://avatars.githubusercontent.com/u/4819899?v=4)](https://github.com/bmartus "bmartus (1 commits)") --- Tags laraveladdresszipzip code ### Embed Badge ![Health badge](/badges/bee-b-zipcode/health.svg) ``` [![Health](https://phpackages.com/badges/bee-b-zipcode/health.svg)](https://phpackages.com/packages/bee-b-zipcode) ``` ### Alternatives [pragmarx/zipcode A worldwide address-by-zipcode searcher. 10265.4k](/packages/pragmarx-zipcode)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[laravel/vapor-cli The Laravel Vapor CLI 31310.7M8](/packages/laravel-vapor-cli)[laravel-zero/framework The Laravel Zero Framework. 3371.4M369](/packages/laravel-zero-framework)[erag/laravel-disposable-email A Laravel package to detect and block disposable email addresses. 226102.4k](/packages/erag-laravel-disposable-email)[vormkracht10/laravel-mails Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app. 24149.7k](/packages/vormkracht10-laravel-mails) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)