Download the PHP package pralhadstha/zipcoder-php without Composer
On this page you can find all versions of the php package pralhadstha/zipcoder-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download pralhadstha/zipcoder-php
More information about pralhadstha/zipcoder-php
Files in pralhadstha/zipcoder-php
Package zipcoder-php
Short Description PHP postal code to address lookup with multi-provider support and automatic fallback
License MIT
Homepage https://github.com/pralhadstha/zipcoder-php
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package zipcoder-php
Zipcoder
A PHP library to convert postal codes and zip codes into structured addresses using multiple geocoding APIs with automatic fallback.
Zipcoder turns any postal code into a normalized address (city, state, province, country, and coordinates) by querying postal code lookup APIs behind a unified interface. If one provider fails or has no data, the next one in the chain picks up automatically. No more vendor lock-in to a single zip code API.
Use cases: shipping & logistics address autofill, checkout form validation, postal code to city/state resolution, international address lookup, and geocoding from zip codes.
Key Features
- 5 built-in postal code providers — GeoNames, Zippopotamus, Zipcodestack, Zipcodebase, and JpPostalCode
- Automatic fallback — Chain of Responsibility pattern tries providers in order until one succeeds
- PSR-16 caching — decorator wraps any provider to cache results and reduce API calls
- PSR-18 HTTP — bring your own HTTP client (Guzzle, Symfony HttpClient, etc.) or use the included zero-dependency curl client
- Normalized results — every provider returns the same
Addressstructure regardless of the underlying API format - 100+ countries — covers postal codes worldwide; Japan-specific provider with English, Japanese, and Kana output
- Zero required dependencies — only PSR interfaces; all implementations are optional
- Extensible — implement the
Providerinterface to add any postal code API - PHP 8.2+ — readonly classes, constructor promotion, strict types throughout
- PHPStan level 9 — fully statically analyzed
Supported Providers
| Provider | Countries | Auth Required | Free Tier | Best For |
|---|---|---|---|---|
| GeoNames | 100+ | Free username | 10,000/day | Primary global provider |
| Zippopotamus | ~60 | None | Unlimited | Quick lookups, zero config |
| Zipcodestack | 210+ | API key | 300/month | Broadest country coverage |
| Zipcodebase | 100+ | API key | 10,000/month | Good middle-ground |
| JpPostalCode | Japan | None | Unlimited | Japan addresses in EN/JA/Kana |
Requirements
- PHP 8.2 or higher
ext-curl(if using the built-inCurlPsr18Client)- A PSR-18 HTTP client (e.g., Guzzle 7) or use the included curl client
Installation
For production, Guzzle is recommended as the HTTP client:
Framework Integration
If you are using a framework, check out our dedicated integration package:
| Framework | Package | Stats |
|---|---|---|
| Laravel | pralhadstha/zipcoder-laravel |
  |
Quick Start
Look up a US zip code and get the city and state in 4 lines:
With Guzzle
With Automatic Fallback (Chain)
Usage
Creating Queries
A Query represents a postal code lookup request. It validates input and normalizes the postal code:
Working with Results
Every provider returns an AddressCollection containing normalized Address objects:
Providers
GeoNames — 100+ countries, free username registration
Returns: `postalCode`, `countryCode`, `city`, `state`, `stateCode`, `province`, `latitude`, `longitude`Zippopotamus — ~60 countries, no authentication needed
Returns: `postalCode`, `countryCode`, `countryName`, `city`, `state`, `stateCode`, `latitude`, `longitude`Zipcodestack — 210+ countries, broadest coverage
Returns: `postalCode`, `countryCode`, `city`, `state`, `province`, `latitude`, `longitude`Zipcodebase — 100+ countries, 10k requests/month free
Returns: `postalCode`, `countryCode`, `city`, `state`, `stateCode`, `province`, `latitude`, `longitude`JpPostalCode — Japan-only, free, supports English/Japanese/Kana
Returns: `postalCode`, `countryCode` (JP), `countryName` (Japan), `state`, `stateCode`, `city`, `district` > Automatically skips non-JP queries in a chain — no API call is made.Chain Provider (Automatic Fallback)
The Chain provider implements the Chain of Responsibility pattern. It tries each provider in order and returns the first successful result. If a provider throws an error or returns no data, it moves to the next one.
How fallback works:
- Each provider is tried in the order given
- If a provider returns addresses, that result is returned immediately
- If a provider throws
NoResultorHttpError, the chain logs a warning and continues - If a provider returns an empty collection, the chain skips to the next
InvalidArgumentexceptions (programming errors) are not caught — they bubble up- If all providers fail, a
NoResultexception is thrown
Cache Provider (PSR-16)
The Cache decorator wraps any provider with PSR-16 caching to avoid redundant API calls:
Cache key format: zipcoder:{COUNTRY_CODE}:{NORMALIZED_CODE} (e.g., zipcoder:US:90210, zipcoder:JP:1000014)
ZipcoderLookup (Provider Registry)
ZipcoderLookup is a convenience aggregator to register and access providers by name:
Full Production Example
Creating a Custom Provider
Implement the Provider interface or extend AbstractHttpProvider to integrate any postal code API:
Then add it to your chain:
Error Handling
Zipcoder uses a clear exception hierarchy:
| Exception | When | Caught by Chain? |
|---|---|---|
NoResult |
No address found for the postal code | Yes (falls back) |
HttpError |
Network failure or HTTP error | Yes (falls back) |
ProviderNotRegistered |
Unknown provider name in ZipcoderLookup::using() |
No |
InvalidArgument |
Invalid input (empty postal code, bad country code) | No (programming error) |
HTTP Client Options
Zipcoder accepts any PSR-18 compatible HTTP client. The first constructor argument is the ClientInterface, the second is the RequestFactoryInterface. Many clients (Guzzle 7, the included curl client) implement both.
| Client | Install | Example |
|---|---|---|
| Built-in curl | Included | new CurlPsr18Client(timeout: 10) |
| Guzzle 7 | composer require guzzlehttp/guzzle |
new \GuzzleHttp\Client(['timeout' => 10]) |
| Symfony HttpClient | composer require symfony/http-client |
PSR-18 adapter |
Testing
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-provider) - Write tests for any new functionality
- Ensure all tests pass (
vendor/bin/phpunit) - Run static analysis (
vendor/bin/phpstan analyse) - Format your code (
vendor/bin/pint) - Submit a pull request
License
Zipcoder is open-sourced software licensed under the MIT License.
Copyright (c) 2026 Pralhad Kumar Shrestha
All versions of zipcoder-php with dependencies
psr/http-client Version ^1.0
psr/http-factory Version ^1.0
psr/http-message Version ^2.0
psr/simple-cache Version ^3.0
psr/log Version ^3.0