Zip API US documentation

The easiest way to perform city/state lookup!

AUTHENTICATION

You are required to provide your API key in your requests. You will be provided an API key when you register for a free account. Your API key have the same privileges as your user account, so be sure to keep them safe.

You authenticate to ZIP API US with HTTP Basic Auth. Provide your email address as the basic auth username and password as the basic auth password.

All API requests must be made over HTTPS.

ENDPOINTS

Find the city and state of a given zip code.

Sample Request: https://service.zipapi.us/zipcode/90210/?X-API-KEY=[your_key]

Method: GET

Optional: Use "fields" parameter and provide any of the following values to receive additional zip code information: geolocation,population,median_age

                
//PHP Example
$url = 'https://service.zipapi.us/zipcode/90210?X-API-KEY=your_api_key&fields=geolocation,population';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_USERPWD, 'youremail' . ":" . 'yourpassword');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);


// EXECUTE:
$result = curl_exec($curl);
if(!$result){
    die("Connection Failure");
}
curl_close($curl);
                
            

Sample Response:

    
{"status":true,"data":{"city":"Beverly Hills","state":"CA","state_fullname": "California","latitude":"34.103131","longitude":"-118.416253","population":"21741"}}
    
                       
curl -X GET 'https://service.zipapi.us/zipcode/90210?X-API-KEY=your_api_key&fields=geolocation,population'
                       
                   

Sample Response:

    
{"status":true,"data":{"city":"Beverly Hills","state":"CA","state_fullname": "California","latitude":"34.103131","longitude":"-118.416253","population":"21741"}}
    
                       

import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://service.zipapi.us/zipcode/90210?X-API-KEY=your_api_key&fields=geolocation,population",
    auth=HTTPBasicAuth("your email", "your password"))

                       
                   

Sample Response:

    
{"status":true,"data":{"city":"Beverly Hills","state":"CA","state_fullname": "California","latitude":"34.103131","longitude":"-118.416253","population":"21741"}}
    

Client side requests are currently not supported.

Find all zip codes within given city and state.

Sample Request:

https://service.zipapi.us/zipcode/zips?X-API-KEY=[your_key]&city=Beverly Hills&state=CA

Method: GET

                
//PHP Example
$url = 'https://service.zipapi.us/zipcode/zips?X-API-KEY=your_api_key&city=Beverly Hills&state=CA';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_USERPWD, 'youremail' . ":" . 'yourpassword');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);


// EXECUTE:
$result = curl_exec($curl);
if(!$result){
    die("Connection Failure");
}
curl_close($curl);
                
            

Sample Response:

    
{"status":true,"data":["90209","90210","90211","90212","90213"]}
    
                                    
curl -X GET 'https://service.zipapi.us/zipcode/zips/90210?X-API-KEY=your_api_key&city=Beverly Hills&state=CA'
                                    
                                

Sample Response:

    
{"status":true,"data":["90209","90210","90211","90212","90213"]}
    
                                    
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://service.zipapi.us/zipcode/zips/90210?X-API-KEY=your_api_key&city=Beverly Hills&state=CA",
    auth=HTTPBasicAuth("your email", "your password"))
                                    
                                

Sample Response:

    
{"status":true,"data":["90209","90210","90211","90212","90213"]}
    

Client side requests are currently not supported.

Find the distance between 2 zip codes. Response is defaulted to miles. You may receive response in km by providing unit as an optional parameter.

Sample Request:

https://service.zipapi.us/zipcode/distance?X-API-KEY=[your_key]&zip1=46220&zip2=90210

Method: GET

Optional: You may provide an optional parameter 'unit' with a value of 'km' for kilometer or 'mi' for miles.

                
//PHP Example
$url = 'https://service.zipapi.us/zipcode/distance?X-API-KEY=your_api_key&zip1=46220&zip2=90210';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_USERPWD, 'youremail' . ":" . 'yourpassword');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);


// EXECUTE:
$result = curl_exec($curl);
if(!$result){
    die("Connection Failure");
}
curl_close($curl);
                
            

Sample Response:

    
{"status":true,"data":{"distance":1816.8075364700221,"unit":"mi"}}
    
                                    
curl -X GET 'https://service.zipapi.us/zipcode/distance?X-API-KEY=your_api_key&zip1=46220&zip2=90210'
                                    
                                

Sample Response:

    
{"status":true,"data":{"distance":1816.8075364700221,"unit":"mi"}}
    
                                    
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://service.zipapi.us/zipcode/distance?X-API-KEY=your_api_key&zip1=46220&zip2=90210",
    auth=HTTPBasicAuth("your email", "your password"))
                                    
                                

Sample Response:

    
{"status":true,"data":{"distance":1816.8075364700221,"unit":"mi"}}
    

Client side requests are currently not supported.

Find the zip codes within radius. Response is defaulted to miles.

Sample Request:

https://service.zipapi.us/zipcode/radius/90210?X-API-KEY=[your_key]&radius=5

Method: GET

Required: Use parameter 'radius' to provide a distance value between 10 - 200 miles.

                
//PHP Example
$url = 'https://service.zipapi.us/zipcode/radius?X-API-KEY=your_api_key&radius=5';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_USERPWD, 'youremail' . ":" . 'yourpassword');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);


// EXECUTE:
$result = curl_exec($curl);
if(!$result){
    die("Connection Failure");
}
curl_close($curl);
                
            

Sample Response:

    
{
    "status": true,
    "data": [
        {
            "ZipCode": "90210",
            "distance": "0"
        },
        {
            "ZipCode": "90077",
            "distance": "2.0723805210278052"
        },
        {
            "ZipCode": "90069",
            "distance": "2.1146886594328533"
        },
        {
            "ZipCode": "90209",
            "distance": "2.2443215484549315"
        },
        {
            "ZipCode": "90213",
            "distance": "2.2443215484549315"
        },
        {
            "ZipCode": "90095",
            "distance": "2.7017962523312495"
        },
        {
            "ZipCode": "90046",
            "distance": "2.724682415256888"
        },
        {
            "ZipCode": "90024",
            "distance": "2.781801455858396"
        },
        {
            "ZipCode": "91604",
            "distance": "2.861208782218938"
        },
        {
            "ZipCode": "90212",
            "distance": "3.0181212235615384"
        },
        {
            "ZipCode": "91423",
            "distance": "3.1159349318911445"
        },
        {
            "ZipCode": "90067",
            "distance": "3.1386642126299464"
        },
        {
            "ZipCode": "90048",
            "distance": "3.1920119219937284"
        },
        {
            "ZipCode": "90211",
            "distance": "3.3281790774731768"
        },
        {
            "ZipCode": "90084",
            "distance": "3.372157317031148"
        },
        {
            "ZipCode": "90073",
            "distance": "3.6396304145950467"
        },
        {
            "ZipCode": "91413",
            "distance": "3.792957922366101"
        },
        {
            "ZipCode": "90035",
            "distance": "3.946173959980035"
        },
        {
            "ZipCode": "91403",
            "distance": "4.094573905639882"
        },
        {
            "ZipCode": "91495",
            "distance": "4.107419133211345"
        },
        {
            "ZipCode": "90049",
            "distance": "4.280099064539145"
        },
        {
            "ZipCode": "90025",
            "distance": "4.287044000579212"
        },
        {
            "ZipCode": "91602",
            "distance": "4.300583583141856"
        },
        {
            "ZipCode": "91608",
            "distance": "4.330233950495441"
        },
        {
            "ZipCode": "91607",
            "distance": "4.356872763300985"
        },
        {
            "ZipCode": "90036",
            "distance": "4.389288883363444"
        },
        {
            "ZipCode": "90064",
            "distance": "4.611786008311598"
        },
        {
            "ZipCode": "90068",
            "distance": "4.976911006233663"
        }
    ]
}
    
                                    
curl -X GET 'https://service.zipapi.us/zipcode/radius/90210?X-API-KEY=your_api_key&radius=5'
                                    
                                

Sample Response:

    
{
    "status": true,
    "data": [
        {
            "ZipCode": "90210",
            "distance": "0"
        },
        {
            "ZipCode": "90077",
            "distance": "2.0723805210278052"
        },
        {
            "ZipCode": "90069",
            "distance": "2.1146886594328533"
        },
        {
            "ZipCode": "90209",
            "distance": "2.2443215484549315"
        },
        {
            "ZipCode": "90213",
            "distance": "2.2443215484549315"
        },
        {
            "ZipCode": "90095",
            "distance": "2.7017962523312495"
        },
        {
            "ZipCode": "90046",
            "distance": "2.724682415256888"
        },
        {
            "ZipCode": "90024",
            "distance": "2.781801455858396"
        },
        {
            "ZipCode": "91604",
            "distance": "2.861208782218938"
        },
        {
            "ZipCode": "90212",
            "distance": "3.0181212235615384"
        },
        {
            "ZipCode": "91423",
            "distance": "3.1159349318911445"
        },
        {
            "ZipCode": "90067",
            "distance": "3.1386642126299464"
        },
        {
            "ZipCode": "90048",
            "distance": "3.1920119219937284"
        },
        {
            "ZipCode": "90211",
            "distance": "3.3281790774731768"
        },
        {
            "ZipCode": "90084",
            "distance": "3.372157317031148"
        },
        {
            "ZipCode": "90073",
            "distance": "3.6396304145950467"
        },
        {
            "ZipCode": "91413",
            "distance": "3.792957922366101"
        },
        {
            "ZipCode": "90035",
            "distance": "3.946173959980035"
        },
        {
            "ZipCode": "91403",
            "distance": "4.094573905639882"
        },
        {
            "ZipCode": "91495",
            "distance": "4.107419133211345"
        },
        {
            "ZipCode": "90049",
            "distance": "4.280099064539145"
        },
        {
            "ZipCode": "90025",
            "distance": "4.287044000579212"
        },
        {
            "ZipCode": "91602",
            "distance": "4.300583583141856"
        },
        {
            "ZipCode": "91608",
            "distance": "4.330233950495441"
        },
        {
            "ZipCode": "91607",
            "distance": "4.356872763300985"
        },
        {
            "ZipCode": "90036",
            "distance": "4.389288883363444"
        },
        {
            "ZipCode": "90064",
            "distance": "4.611786008311598"
        },
        {
            "ZipCode": "90068",
            "distance": "4.976911006233663"
        }
    ]
}
    
                                    
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://service.zipapi.us/zipcode/radius/90210?X-API-KEY=your_api_key&radius=50",
    auth=HTTPBasicAuth("your email", "your password"))
                                    
                                

Sample Response:

    
{
    "status": true,
    "data": [
        {
            "ZipCode": "90210",
            "distance": "0"
        },
        {
            "ZipCode": "90077",
            "distance": "2.0723805210278052"
        },
        {
            "ZipCode": "90069",
            "distance": "2.1146886594328533"
        },
        {
            "ZipCode": "90209",
            "distance": "2.2443215484549315"
        },
        {
            "ZipCode": "90213",
            "distance": "2.2443215484549315"
        },
        {
            "ZipCode": "90095",
            "distance": "2.7017962523312495"
        },
        {
            "ZipCode": "90046",
            "distance": "2.724682415256888"
        },
        {
            "ZipCode": "90024",
            "distance": "2.781801455858396"
        },
        {
            "ZipCode": "91604",
            "distance": "2.861208782218938"
        },
        {
            "ZipCode": "90212",
            "distance": "3.0181212235615384"
        },
        {
            "ZipCode": "91423",
            "distance": "3.1159349318911445"
        },
        {
            "ZipCode": "90067",
            "distance": "3.1386642126299464"
        },
        {
            "ZipCode": "90048",
            "distance": "3.1920119219937284"
        },
        {
            "ZipCode": "90211",
            "distance": "3.3281790774731768"
        },
        {
            "ZipCode": "90084",
            "distance": "3.372157317031148"
        },
        {
            "ZipCode": "90073",
            "distance": "3.6396304145950467"
        },
        {
            "ZipCode": "91413",
            "distance": "3.792957922366101"
        },
        {
            "ZipCode": "90035",
            "distance": "3.946173959980035"
        },
        {
            "ZipCode": "91403",
            "distance": "4.094573905639882"
        },
        {
            "ZipCode": "91495",
            "distance": "4.107419133211345"
        },
        {
            "ZipCode": "90049",
            "distance": "4.280099064539145"
        },
        {
            "ZipCode": "90025",
            "distance": "4.287044000579212"
        },
        {
            "ZipCode": "91602",
            "distance": "4.300583583141856"
        },
        {
            "ZipCode": "91608",
            "distance": "4.330233950495441"
        },
        {
            "ZipCode": "91607",
            "distance": "4.356872763300985"
        },
        {
            "ZipCode": "90036",
            "distance": "4.389288883363444"
        },
        {
            "ZipCode": "90064",
            "distance": "4.611786008311598"
        },
        {
            "ZipCode": "90068",
            "distance": "4.976911006233663"
        }
    ]
}
    

Client side requests are currently not supported.

Find out the population of a given zipcode. Total population will be provided as the default response for the given zip code. *Population data is based on the 2010 Census

Sample Request: https://service.zipapi.us/population/zipcode/46220/?X-API-KEY=[your_key]

Method: GET

Optional: You may include an additional parameter "fields" and specify any of the following values: male_population, female_population

                        
//PHP Example
$url = 'https://service.zipapi.us/population/zipcode/90210?X-API-KEY=your_api_key&fields=male_population,female_population'';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_USERPWD, 'youremail' . ":" . 'yourpassword');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);


// EXECUTE:
$result = curl_exec($curl);
if(!$result){
    die("Connection Failure");
}
curl_close($curl);
                        
                    

Sample Response:

                        
{"status":true,"data":{"population":"21741","male_population":"10292","female_population":"11449"}}
                        
                    
                                    
curl -X GET 'https://service.zipapi.us/population/zipcode/90210?X-API-KEY=your_api_key&fields=male_population,female_population'
                                    
                                

Sample Response:

                        
{"status":true,"data":{"population":"21741","male_population":"10292","female_population":"11449"}}
                        
                    
                                    
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://service.zipapi.us/population/zipcode/90210?X-API-KEY=your_api_key&fields=male_population,female_population",
    auth=HTTPBasicAuth("your email", "your password"))
                                    
                                

Sample Response:

                        
{"status":true,"data":{"population":"21741","male_population":"10292","female_population":"11449"}}
                        
                    

Client side requests are currently not supported.

Find the average age based on a given zip code. *Age data is based on the 2010 Census.

Sample Request: https://service.zipapi.us/age/zipcode/90210/?X-API-KEY=[your_key]&fields=male_age,female_age

Method: GET

                
//PHP Example
$url = 'https://service.zipapi.us/age/zipcode/90210?X-API-KEY=your_api_key';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_USERPWD, 'youremail' . ":" . 'yourpassword');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);


// EXECUTE:
$result = curl_exec($curl);
if(!$result){
    die("Connection Failure");
}
curl_close($curl);
                
            

Sample Response:

    
{"status":true,"data":{"median_age":"47.5","male_age":"47.9","female_age":"47.1"}}
    
                                    
curl -X GET 'https://service.zipapi.us/age/zipcode/90210?X-API-KEY=your_api_key&fields=male_age,female_age'
                                    
                                

Sample Response:

    
{"status":true,"data":{"median_age":"47.5","male_age":"47.9","female_age":"47.1"}}
    
                                    
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://service.zipapi.us/age/zipcode/90210?X-API-KEY=your_api_key",
    auth=HTTPBasicAuth("your email", "your password"))
                                    
                                

Sample Response:

    
{"status":true,"data":{"median_age":"47.5","male_age":"47.9","female_age":"47.1"}}
    

Client side requests are currently not supported.

Error Codes

The error codes are returned via HTTP response code .

Sample Failed Response

                
{"status": false,"message": "Zip could not be found"}