README

Official PHP client for the zipcodestack.com API.

Website: zipcodestack.com
API: search zip/postal codes, compute distances, check API status
License: MIT

Installation

Install via Composer:

composer require zipcodestack/zipcodestack-php

Requires PHP 8.0+.

Authentication

Provide your API key via constructor or environment variable ZIPCODESTACK_API_KEY. By default, the client authenticates with an apikey header. You can switch to query param auth.

<?php
use ZipCodeStack\Client;

// Option 1: via env var
// put in your shell or server env: export ZIPCODESTACK_API_KEY="your_key"
$client = new Client();

// Option 2: pass API key directly
$client = new Client('your_key');

// Option 3: query param auth
$client = new Client('your_key', ['auth_method' => 'query']);

Usage

<?php
declare(strict_types=1);

use ZipCodeStack\Client;
use ZipCodeStack\Exception\AuthenticationException;
use ZipCodeStack\Exception\RateLimitException;
use ZipCodeStack\Exception\ApiException;

$client = new Client(getenv('ZIPCODESTACK_API_KEY') ?: 'your_key');

// Search endpoint
$result = $client->search([
    'query' => '10001', // or any supported parameter; see docs
]);

// Distance endpoint
$distance = $client->distance('10001', '94105', [
    'unit' => 'mi', // or 'km'
]);

// Status endpoint
$status = $client->status();

Error handling

try {
    $result = $client->search(['query' => '10001']);
} catch (AuthenticationException $e) {
    // invalid or missing API key
} catch (RateLimitException $e) {
    // too many requests; consider $e->getRetryAfter()
} catch (ApiException $e) {
    // other API or network errors
}

Configuration

You may pass options to configure the client:

$client = new Client('your_key', [
    'base_uri' => 'https://api.zipcodestack.com',
    'api_base_path' => '/v1',
    'timeout' => 10.0,
    'connect_timeout' => 5.0,
    'headers' => [ 'X-Custom' => 'value' ],
    'auth_method' => 'header', // or 'query'
]);

See the official site for parameter details and response formats: zipcodestack.com.

Contributing

Issues and PRs are welcome. Please include tests and adhere to PSR standards.

zipcodestack / zipcodestack-php

Maintainers

Details