PHP code example of pralhadstha / zipcoder-php

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

pralhadstha / zipcoder-php example snippets

use Pralhad\Zipcoder\Http\CurlPsr18Client;
use Pralhad\Zipcoder\Provider\Zippopotamus;
use Pralhad\Zipcoder\Query;

$http = new CurlPsr18Client();
$provider = new Zippopotamus($http, $http);

$result = $provider->lookup(Query::create('90210', 'US'));

$address = $result->first();
echo $address->city;      // "Beverly Hills"
echo $address->state;     // "California"
echo $address->stateCode; // "CA"
echo $address->latitude;  // 34.0901
echo $address->longitude; // -118.4065

use GuzzleHttp\Client;
use Pralhad\Zipcoder\Provider\GeoNames;
use Pralhad\Zipcoder\Query;

$guzzle = new Client(['timeout' => 10]);
$provider = new GeoNames($guzzle, $guzzle, username: 'your_geonames_username');

$result = $provider->lookup(Query::create('100-0001', 'JP'));
echo $result->first()->city; // "Chiyoda"

use Pralhad\Zipcoder\Http\CurlPsr18Client;
use Pralhad\Zipcoder\Provider\Chain;
use Pralhad\Zipcoder\Provider\GeoNames;
use Pralhad\Zipcoder\Provider\JpPostalCode;
use Pralhad\Zipcoder\Provider\Zippopotamus;
use Pralhad\Zipcoder\Query;

$http = new CurlPsr18Client();

$provider = new Chain([
    new JpPostalCode($http, $http),                       // Japan: free, best data
    new Zippopotamus($http, $http),                        // 60 countries: free, fast
    new GeoNames($http, $http, 'your_geonames_username'),  // 100+ countries: free tier
]);

// Japan postal code uses JpPostalCode provider
$result = $provider->lookup(Query::create('100-0014', 'JP'));

// For US zip code, JpPostalCode skips (not JP), Zippopotamus handles it
$result = $provider->lookup(Query::create('90210', 'US'));

use Pralhad\Zipcoder\Query;

$query = Query::create('90210', 'US');
$query->postalCode;           // "90210"
$query->countryCode;          // "US"
$query->normalizedPostalCode(); // "90210" (strips hyphens and spaces)

// Japanese postal codes with hyphens are normalized
$query = Query::create('100-0014', 'JP');
$query->normalizedPostalCode(); // "1000014"

$result = $provider->lookup(Query::create('10005', 'US'));

// Access the first result
$address = $result->first();
$address->postalCode;   // "10005"
$address->countryCode;  // "US"
$address->countryName;  // "United States" (if available)
$address->city;         // "New York City"
$address->state;        // "New York"
$address->stateCode;    // "NY"
$address->province;     // Province (if available)
$address->district;     // District (if available)
$address->latitude;     // 40.7063
$address->longitude;    // -74.0089
$address->provider;     // "zipcodebase" (which provider returned this)

// Iterate all results
foreach ($result as $address) {
    echo "{$address->city}, {$address->state}\n";
}

// Collection helpers
$result->count();    // Number of addresses
$result->isEmpty();  // true if no results
$result->toArray();  // Convert all addresses to arrays

use Pralhad\Zipcoder\Provider\GeoNames;

// Register at https://www.geonames.org/login to get a free username
$provider = new GeoNames($httpClient, $requestFactory, username: 'your_username');
$result = $provider->lookup(Query::create('100-0001', 'JP'));

use Pralhad\Zipcoder\Provider\Zippopotamus;

// No API key or username needed
$provider = new Zippopotamus($httpClient, $requestFactory);
$result = $provider->lookup(Query::create('90210', 'US'));

use Pralhad\Zipcoder\Provider\Zipcodestack;

// Get an API key at https://zipcodestack.com
$provider = new Zipcodestack($httpClient, $requestFactory, apiKey: 'your_api_key');
$result = $provider->lookup(Query::create('44600', 'NP'));

use Pralhad\Zipcoder\Provider\Zipcodebase;

// Get an API key at https://zipcodebase.com
$provider = new Zipcodebase($httpClient, $requestFactory, apiKey: 'your_api_key');
$result = $provider->lookup(Query::create('10005', 'US'));

use Pralhad\Zipcoder\Provider\JpPostalCode;

// English output (default)
$provider = new JpPostalCode($httpClient, $requestFactory, locale: 'en');
$result = $provider->lookup(Query::create('100-0014', 'JP'));
$result->first()->city; // "Chiyoda-ku"

// Japanese output
$provider = new JpPostalCode($httpClient, $requestFactory, locale: 'ja');
$result = $provider->lookup(Query::create('100-0014', 'JP'));
$result->first()->city; // "千代田区"

// Kana output
$provider = new JpPostalCode($httpClient, $requestFactory, locale: 'kana');
$result = $provider->lookup(Query::create('100-0014', 'JP'));
$result->first()->city; // "チヨダク"

use Pralhad\Zipcoder\Provider\Chain;
use Psr\Log\LoggerInterface;

$chain = new Chain(
    providers: [
        new JpPostalCode($http, $http),
        new Zippopotamus($http, $http),
        new GeoNames($http, $http, 'username'),
        new Zipcodebase($http, $http, 'api_key'),
        new Zipcodestack($http, $http, 'api_key'),
    ],
    logger: $psrLogger, // Optional PSR-3 logger for debugging fallback behavior
);

$result = $chain->lookup(Query::create('44600', 'NP'));

use Pralhad\Zipcoder\Provider\Cache;
use Psr\SimpleCache\CacheInterface;

// Wrap any provider (or a chain) with caching
$cached = new Cache(
    provider: $chain,
    cache: $psrCache,    // Any PSR-16 cache (Laravel, Symfony, php-cache, etc.)
    ttl: 86400,          // Cache for 24 hours (default)
);

// First call: hits the API, stores result in cache
$result = $cached->lookup(Query::create('90210', 'US'));

// Second call: returns from cache, no API call
$result = $cached->lookup(Query::create('90210', 'US'));

use Pralhad\Zipcoder\ZipcoderLookup;

$zipcoder = new ZipcoderLookup();
$zipcoder->registerProvider($cachedChain);
$zipcoder->registerProvider(new Zippopotamus($http, $http));

// Use the first registered provider
$result = $zipcoder->lookup(Query::create('90210', 'US'));

// Use a specific provider by name
$result = $zipcoder->using('zippopotamus')->lookup(Query::create('90210', 'US'));

// List registered providers
$zipcoder->getRegisteredProviders(); // ['cache(chain)', 'zippopotamus']

use Pralhad\Zipcoder\Http\CurlPsr18Client;
use Pralhad\Zipcoder\Provider\Cache;
use Pralhad\Zipcoder\Provider\Chain;
use Pralhad\Zipcoder\Provider\GeoNames;
use Pralhad\Zipcoder\Provider\JpPostalCode;
use Pralhad\Zipcoder\Provider\Zipcodebase;
use Pralhad\Zipcoder\Provider\Zipcodestack;
use Pralhad\Zipcoder\Provider\Zippopotamus;
use Pralhad\Zipcoder\Query;
use Pralhad\Zipcoder\ZipcoderLookup;

$http = new CurlPsr18Client(timeout: 10);

$chain = new Chain([
    new JpPostalCode($http, $http),
    new Zippopotamus($http, $http),
    new GeoNames($http, $http, 'your_username'),
    new Zipcodebase($http, $http, 'your_api_key'),
    new Zipcodestack($http, $http, 'your_api_key'),
]);

$provider = new Cache($chain, $yourPsr16Cache, ttl: 3600);

$zipcoder = new ZipcoderLookup();
$zipcoder->registerProvider($provider);

$result = $zipcoder->lookup(Query::create('100-0014', 'JP'));
$address = $result->first();

echo "{$address->city}, {$address->state}, {$address->countryCode}";
// "Chiyoda-ku, Tokyo, JP"

use Pralhad\Zipcoder\Contract\Provider;
use Pralhad\Zipcoder\Provider\AbstractHttpProvider;
use Pralhad\Zipcoder\Query;
use Pralhad\Zipcoder\Result\Address;
use Pralhad\Zipcoder\Result\AddressCollection;

final class MyApiProvider extends AbstractHttpProvider
{
    public function lookup(Query $query): AddressCollection
    {
        $url = "https://my-api.com/lookup?code={$query->postalCode}&country={$query->countryCode}";
        $data = $this->fetchJson($url);

        $addresses = array_map(
            fn (array $item) => new Address(
                postalCode: $query->postalCode,
                countryCode: $query->countryCode,
                city: $item['city'] ?? null,
                state: $item['region'] ?? null,
                latitude: isset($item['lat']) ? (float) $item['lat'] : null,
                longitude: isset($item['lng']) ? (float) $item['lng'] : null,
                provider: $this->getName(),
            ),
            $data['results'] ?? [],
        );

        return new AddressCollection($addresses);
    }

    public function getName(): string
    {
        return 'my-api';
    }
}

$chain = new Chain([
    new MyApiProvider($http, $http),
    new GeoNames($http, $http, 'username'),
]);

use Pralhad\Zipcoder\Exception\NoResult;
use Pralhad\Zipcoder\Exception\HttpError;
use Pralhad\Zipcoder\Exception\InvalidArgument;

try {
    $result = $provider->lookup(Query::create('99999', 'XX'));
} catch (NoResult $e) {
    // No provider could resolve this postal code
    echo "Not found: {$e->getMessage()}";
} catch (HttpError $e) {
    // All providers had network/HTTP errors
    echo "Service error: {$e->getMessage()}";
} catch (InvalidArgument $e) {
    // Bad input — fix the query
    echo "Invalid input: {$e->getMessage()}";
}

bash
composer 

bash
composer