MENU navbar-image

Introduction

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

Authenticate requests to this API's endpoints by sending a apikey header with the value "{YOUR_API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Endpoints

GET /v1/status

requires authentication

Returns the remaining requests for the given API key.

Example request:
curl --request GET \
    --get "https://api.zipcodestack.com/v1/status" \
    --header "apikey: {YOUR_API_KEY}"
const url = new URL(
    "https://api.zipcodestack.com/v1/status"
);

const headers = {
    "apikey": "{YOUR_API_KEY}",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.zipcodestack.com/v1/status',
    [
        'headers' => [
            'apikey' => '{YOUR_API_KEY}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.zipcodestack.com/v1/status'
headers = {
  'apikey': '{YOUR_API_KEY}'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-remaining: 1245477
 

{
    "requests": 1245477
}

Request      

GET v1/status

Headers

apikey      

Example: {YOUR_API_KEY}

requires authentication

Search zip codes with this endpoint

Example request:
curl --request GET \
    --get "https://api.zipcodestack.com/v1/search?codes=99501%2C90210&country=us" \
    --header "apikey: {YOUR_API_KEY}"
const url = new URL(
    "https://api.zipcodestack.com/v1/search"
);

const params = {
    "codes": "99501,90210",
    "country": "us",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "apikey": "{YOUR_API_KEY}",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.zipcodestack.com/v1/search',
    [
        'headers' => [
            'apikey' => '{YOUR_API_KEY}',
        ],
        'query' => [
            'codes'=> '99501,90210',
            'country'=> 'us',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.zipcodestack.com/v1/search'
params = {
  'codes': '99501,90210',
  'country': 'us',
}
headers = {
  'apikey': '{YOUR_API_KEY}'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

Show headers 
content-type: application/json; charset=UTF-8
charset: utf-8
cache-control: no-cache, private
x-ratelimit-remaining: 1245475
 

{
    "query": {
        "codes": [
            "99501",
            "90210"
        ],
        "country": "us"
    },
    "results": {
        "99501": [
            {
                "postal_code": "99501",
                "country_code": "US",
                "latitude": 61.2116,
                "longitude": -149.8761,
                "city": "Anchorage",
                "state": "Alaska",
                "city_en": "Anchorage",
                "state_en": "Alaska",
                "state_code": "AK"
            }
        ],
        "90210": [
            {
                "postal_code": "90210",
                "country_code": "US",
                "latitude": 34.0901,
                "longitude": -118.4065,
                "city": "Beverly Hills",
                "state": "California",
                "city_en": "Beverly Hills",
                "state_en": "California",
                "state_code": "CA"
            }
        ]
    }
}

GET /v1/distance

requires authentication

Calculates the distance between one and other postalcodes

Example request:
curl --request GET \
    --get "https://api.zipcodestack.com/v1/distance?code=99501&compare=90210%2C15106&country=us&unit=km" \
    --header "apikey: {YOUR_API_KEY}"
const url = new URL(
    "https://api.zipcodestack.com/v1/distance"
);

const params = {
    "code": "99501",
    "compare": "90210,15106",
    "country": "us",
    "unit": "km",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "apikey": "{YOUR_API_KEY}",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.zipcodestack.com/v1/distance',
    [
        'headers' => [
            'apikey' => '{YOUR_API_KEY}',
        ],
        'query' => [
            'code'=> '99501',
            'compare'=> '90210,15106',
            'country'=> 'us',
            'unit'=> 'km',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.zipcodestack.com/v1/distance'
params = {
  'code': '99501',
  'compare': '90210,15106',
  'country': 'us',
  'unit': 'km',
}
headers = {
  'apikey': '{YOUR_API_KEY}'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

Show headers 
content-type: application/json; charset=UTF-8
charset: utf-8
cache-control: no-cache, private
x-ratelimit-remaining: 1245473
 

{
    "query": {
        "code": "99501",
        "compare": [
            "90210",
            "15106"
        ],
        "country": "us",
        "unit": "km"
    },
    "results": {
        "90210": 3754.89,
        "15106": 5115.42
    }
}

Request      

GET v1/distance

Headers

apikey      

Example: {YOUR_API_KEY}

Query Parameters

code   string   

string Zip code. Example: 99501

compare   string   

string The list of zip codes to compare to. Example: 90210,15106

country   string   

string Two letter country code. Example: us

unit   string  optional  

The unit of distance, can be kilometers or miles. Defaults to km. Example: km