Developer Guide

ZIP Code API — PHP Examples

Working code using curl, Guzzle, and WordPress. Ideal for eCommerce checkout validation, WooCommerce, and any PHP backend. Get a free API key instantly.

⚡ Get Free API Key Full API Docs →

The Quick Answer

The ZipCodesToGo ZIP Code API is a standard REST/JSON API. In PHP, the fastest integration uses curl or the file_get_contents() stream wrapper. For Laravel and Symfony projects, Guzzle is the cleanest option. For WordPress, use wp_remote_get().

curl (Plain PHP)

zip_lookup.php — curl example

<?php
$api_key = 'zcg_your_key_here';
$zip     = '90210';
$url     = "https://api.zipcodestogo.com/v1/zip/{$zip}";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: {$api_key}"],
    CURLOPT_TIMEOUT        => 5,
]);

$body    = curl_exec($ch);
$status  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("API error: HTTP {$status}");
}

$result = json_decode($body, true)['data'];

echo $result['city'];    // Beverly Hills
echo $result['state'];   // CA
echo $result['county'];  // Los Angeles
echo $result['lat'];     // 34.0901

Reusable Function + Error Handling

ZipClient.php — production-ready class

<?php
class ZipClient {
    private string $apiKey;
    private const BASE = 'https://api.zipcodestogo.com/v1';

    public function __construct(string $apiKey) {
        $this->apiKey = $apiKey;
    }

    public function lookup(string $zip): array {
        if (!preg_match('/^\d{5}$/', $zip)) {
            throw new InvalidArgumentException("Invalid ZIP: {$zip}");
        }
        $ch = curl_init(self::BASE . "/zip/{$zip}");
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ["X-Api-Key: {$this->apiKey}"],
            CURLOPT_TIMEOUT        => 5,
        ]);
        $body   = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        match ($status) {
            200  => null,
            404  => throw new RuntimeException("ZIP {$zip} not found"),
            401  => throw new RuntimeException('Invalid API key'),
            429  => throw new RuntimeException('Rate limit reached'),
            default => throw new RuntimeException("HTTP {$status}"),
        };
        return json_decode($body, true)['data'];
    }
}

// Usage
$client   = new ZipClient($_ENV['ZIP_API_KEY']);
$location = $client->lookup('10001');
echo "{$location['city']}, {$location['state']}"; // New York, NY

WordPress Integration

functions.php — WordPress / wp_remote_get()

<?php
// Add to functions.php or a custom plugin
// Store your key: Settings → ZIP API Key, or define in wp-config.php

function zcg_lookup_zip( $zip ): ?array {
    $api_key = defined( 'ZCG_API_KEY' ) ? ZCG_API_KEY : get_option( 'zcg_api_key' );
    if ( ! $api_key || ! preg_match( '/^\d{5}$/', $zip ) ) return null;

    $response = wp_remote_get(
        "https://api.zipcodestogo.com/v1/zip/{$zip}",
        [ 'headers' => [ 'X-Api-Key' => $api_key ], 'timeout' => 5 ]
    );

    if ( is_wp_error( $response ) ) return null;
    if ( wp_remote_retrieve_response_code( $response ) !== 200 ) return null;

    $body = json_decode( wp_remote_retrieve_body( $response ), true );
    return $body['data'] ?? null;
}

// Example: auto-fill city/state in a form
// $data = zcg_lookup_zip( '90210' );
// echo $data['city']; // Beverly Hills

HTTP Status Codes

Status	Meaning	PHP handling
`200`	Success	Parse `$body['data']`
`404`	ZIP not found	Show error to user, clear fields
`401`	Bad API key	Check `$_ENV['ZIP_API_KEY']`
`429`	Rate limit	Cache responses, or upgrade plan
`5xx`	Server error	Retry or serve cached data

More Developer Guides