PHPackages pralhadstha/zipcoder-laravel - 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. pralhadstha/zipcoder-laravel ActiveLibrary[Utility & Helpers](/categories/utility) pralhadstha/zipcoder-laravel ============================ Laravel package to resolve postal codes and zip codes to addresses. Supports multiple geocoding providers with automatic failover, built-in caching, Facade support, and publishable config. v1.0.0(2mo ago)04MITPHPPHP ^8.2CI passing Since Apr 5Pushed 2mo agoCompare [ Source](https://github.com/pralhadstha/Zipcoder-laravel)[ Packagist](https://packagist.org/packages/pralhadstha/zipcoder-laravel)[ RSS](/packages/pralhadstha-zipcoder-laravel/feed)WikiDiscussions main Synced 2w ago READMEChangelogDependencies (6)Versions (2)Used By (0) Zipcoder Laravel ================ [](#zipcoder-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/0c40949ce781697b4a2a7e5dc7c0a9cf0a3ea56e5ed2c1cfad8df55e2234d059/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7072616c686164737468612f7a6970636f6465722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pralhadstha/zipcoder-laravel)[![Total Downloads](https://camo.githubusercontent.com/071c158c5775f69f296831ec8aad58701232c4f41637b26690221cc9b59c6026/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7072616c686164737468612f7a6970636f6465722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pralhadstha/zipcoder-laravel)[![License](https://camo.githubusercontent.com/baa408a71ab5fd0d952bf08b58e91ba33f3e573cf26435d4b8dc94a920231a04/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7072616c686164737468612f7a6970636f6465722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/cd6c829989ccf49cd86b2cd598fedb9524c1187764fa53b86eef7aee14edefe4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7072616c686164737468612f7a6970636f6465722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](composer.json)[![Tests](https://camo.githubusercontent.com/f71c23a099cfd927ae15b5cc4718a6256ba64b93e216391687dee8dabef82507/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7072616c686164737468612f7a6970636f6465722d6c61726176656c2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/pralhadstha/zipcoder-laravel/actions) A Laravel package to resolve postal codes and zip codes to addresses. Supports multiple geocoding providers with automatic failover, built-in caching, Facade support, and publishable config. Why Zipcoder Laravel? --------------------- [](#why-zipcoder-laravel) - **Multiple providers** — GeoNames, Zippopotamus, Zipcodestack, Zipcodebase, and JP Postal Code out of the box - **Automatic failover** — Chain of Responsibility pattern tries providers in order until one succeeds - **Built-in caching** — PSR-16 cache integration with configurable TTL and store, reducing API calls - **Zero config for free providers** — Zippopotamus and JP Postal Code work without API keys - **Custom providers** — Register your own provider via config, no package forking needed - **Laravel-native** — Auto-discovery, Facade, publishable config, env-driven settings Requirements ------------ [](#requirements) - PHP 8.2 or higher - Laravel 11, 12, or 13 Installation ------------ [](#installation) ``` composer require pralhadstha/zipcoder-laravel ``` The package auto-discovers the service provider and facade. No manual registration needed. Publish the configuration file: ``` php artisan vendor:publish --tag=zipcoder-config ``` Configuration ------------- [](#configuration) The published config file (`config/zipcoder.php`) has four sections: ### HTTP Client [](#http-client) ``` 'http' => [ 'timeout' => env('ZIPCODER_HTTP_TIMEOUT', 10), 'connect_timeout' => env('ZIPCODER_HTTP_CONNECT_TIMEOUT', 5), ], ``` Uses Guzzle 7+ (ships with Laravel) implementing PSR-18. You can override by binding your own `ClientInterface` in the container. ### Providers [](#providers) Configure credentials for each provider: ``` 'providers' => [ 'geonames' => [ 'username' => env('GEONAMES_USERNAME'), ], 'zippopotamus' => [ 'enabled' => true, ], 'zipcodestack' => [ 'api_key' => env('ZIPCODESTACK_API_KEY'), ], 'zipcodebase' => [ 'api_key' => env('ZIPCODEBASE_API_KEY'), ], 'jp-postal-code' => [ 'enabled' => true, 'locale' => env('JP_POSTAL_CODE_LOCALE', 'en'), ], ], ``` Providers with missing credentials are automatically skipped. ### Chain Order [](#chain-order) Controls the order in which providers are attempted. The first provider to return a result wins: ``` 'chain' => [ 'jp-postal-code', 'zippopotamus', 'geonames', 'zipcodebase', 'zipcodestack', ], ``` ### Cache [](#cache) ``` 'cache' => [ 'enabled' => env('ZIPCODER_CACHE_ENABLED', true), 'ttl' => env('ZIPCODER_CACHE_TTL', 86400), // 24 hours 'store' => env('ZIPCODER_CACHE_STORE'), // null = default store ], ``` Usage ----- [](#usage) ### Basic Lookup [](#basic-lookup) ``` use Pralhad\Zipcoder\Laravel\Facades\Zipcoder; use Pralhad\Zipcoder\Query; $results = Zipcoder::lookup(Query::create('10001', 'US')); $address = $results->first(); echo $address->city; // "New York" echo $address->state; // "New York" echo $address->stateCode; // "NY" echo $address->countryCode; // "US" echo $address->latitude; // 40.7484 echo $address->longitude; // -73.9967 ``` ### Iterating Results [](#iterating-results) ``` $results = Zipcoder::lookup(Query::create('100-0001', 'JP')); foreach ($results as $address) { echo "{$address->city}, {$address->state}" . PHP_EOL; } ``` ### Checking for Results [](#checking-for-results) ``` $results = Zipcoder::lookup(Query::create('10001', 'US')); if ($results->isEmpty()) { // No addresses found } echo $results->count(); // Number of addresses returned ``` ### Converting to Array [](#converting-to-array) ``` $array = $results->first()->toArray(); // or all results $allArrays = $results->toArray(); ``` Available Providers ------------------- [](#available-providers) ProviderCredentialsCountriesNotes**Zippopotamus**NoneMultipleFree, no API key required. Default fallback.**GeoNames**`username`MultipleFree account at [geonames.org](https://www.geonames.org/)**Zipcodebase**`api_key`MultipleAPI key from [zipcodebase.com](https://zipcodebase.com/)**Zipcodestack**`api_key`MultipleAPI key from [zipcodestack.com](https://zipcodestack.com/)**JP Postal Code**NoneJapan onlySupports `en` and `ja` localesCustom Providers ---------------- [](#custom-providers) Create a class implementing `Pralhad\Zipcoder\Contract\Provider`: ``` namespace App\Zipcoder; use Pralhad\Zipcoder\Contract\Provider; use Pralhad\Zipcoder\Query; use Pralhad\Zipcoder\Result\AddressCollection; use Psr\Http\Client\ClientInterface; use Psr\Http\Message\RequestFactoryInterface; class MyProvider implements Provider { public function __construct( private ClientInterface $client, private RequestFactoryInterface $requestFactory, private string $api_url, ) {} public function lookup(Query $query): AddressCollection { // Your implementation } public function getName(): string { return 'my-provider'; } } ``` Register it in the config: ``` 'providers' => [ // ... built-in providers 'my-provider' => [ 'class' => \App\Zipcoder\MyProvider::class, 'enabled' => true, 'api_url' => 'https://api.example.com', ], ], 'chain' => [ 'my-provider', // Add to chain order 'zippopotamus', // ... ], ``` The `$client` and `$requestFactory` are injected automatically. Extra config keys (like `api_url`) are passed as constructor parameters. Caching ------- [](#caching) Caching is enabled by default with a 24-hour TTL. Results are cached per postal code and country code using Laravel's cache store. To disable caching: ``` ZIPCODER_CACHE_ENABLED=false ``` To change TTL (in seconds): ``` ZIPCODER_CACHE_TTL=3600 ``` To use a specific cache store: ``` ZIPCODER_CACHE_STORE=redis ``` Facade API Reference -------------------- [](#facade-api-reference) ``` // Look up addresses for a postal code Zipcoder::lookup(Query $query): AddressCollection // Use a specific provider (bypasses chain) Zipcoder::using(string $providerName): Provider // Register an additional provider at runtime Zipcoder::registerProvider(Provider $provider): ZipcoderLookup // List all registered provider names Zipcoder::getRegisteredProviders(): array ``` Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) If you discover a security vulnerability, please see our [Security Policy](.github/SECURITY.md). Do not open a public issue for security vulnerabilities. License ------- [](#license) MIT. See [LICENSE](LICENSE) for details. ### Health Score 37 — LowBetter than 81% of packages Maintenance84 Actively maintained with recent releases Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 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 Unknown Total 1 Last Release 83d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2d46fb8b473d604d2f5eb4e27451ef88b44e10a430c0a0ce89b4e501fcfe95b2?d=identicon)[pralhad](/maintainers/pralhad) --- Top Contributors [![pralhadstha](https://avatars.githubusercontent.com/u/6309194?v=4)](https://github.com/pralhadstha "pralhadstha (7 commits)") --- Tags address-validationgeocodinggeolocationlaravellaravel-packagemulti-providerphppostal-codepostal-code-lookupzip-code-lookupzipcodezipcodesearchlaravelgeocodingaddresszipcodelookuppostal-codezipcoder ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/pralhadstha-zipcoder-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/pralhadstha-zipcoder-laravel/health.svg)](https://phpackages.com/packages/pralhadstha-zipcoder-laravel) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.1M337](/packages/psalm-plugin-laravel)[laravel/ai The official AI SDK for Laravel. 9782.1M162](/packages/laravel-ai)[moonshine/moonshine Laravel administration panel 1.3k239.9k76](/packages/moonshine-moonshine)[linkxtr/laravel-qrcode A clean, modern, and easy-to-use QR code generator for Laravel 3614.9k](/packages/linkxtr-laravel-qrcode)[tomshaw/electricgrid A feature-rich Livewire package designed for projects that require dynamic, interactive data tables. 119.2k](/packages/tomshaw-electricgrid) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)