AUTHENTICATION

You are required to provide your API key in all of your requests. You will be provided an API key when you register for a free account. Your API key is unique to your account. The number of requests you make with this key will count towards your limit so be sure to keep it safe.

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,county,population,median_age

Code Samples
PHP EXAMPLE
Sample Request:
                
//PHP Example
$url = 'https://service.zipapi.us/hospital/radius/90210?X-API-KEY=your_api_key&radius=5';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
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 EXAMPLE
Sample Request:
                       
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"}}
PYTHON EXAMPLE
Sample Request:
                       

import requests
r = requests.get("https://service.zipapi.us/zipcode/90210?X-API-KEY=your_api_key&fields=geolocation,population")
print(r.text)
Sample Response: 
    
{"status":true,"data":{"city":"Beverly Hills","state":"CA","state_fullname": "California","latitude":"34.103131","longitude":"-118.416253","population":"21741"}}
JAVASCRIPT EXAMPLE
Sample Request:
                        
    var zipcode = 90210;
    var clientKey = 'Your js key';
    var url = "https://service.zipapi.us/zipcode/" + zipcode + "?X-API-KEY=" + clientKey + "&fields=geolocation,population";


    var xhttp = new XMLHttpRequest();


    xhttp.onreadystatechange = function() {

        if (this.readyState == 4) {

            document.getElementById("demo").innerHTML = this.responseText;
        }


    };

    xhttp.open("GET", url, true);
    xhttp.send();
Sample Response: 
    
{"status":true,"data":{"city":"Beverly Hills","state":"CA","state_fullname": "California","latitude":"34.103131","longitude":"-118.416253","population":"21741"}}

Find the county or counties of a given zip code.

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

Method: GET

Code Samples
PHP EXAMPLE
Sample Request:
                
//PHP Example
$url = 'https://service.zipapi.us/zipcode/county/47858?X-API-KEY=your_api_key';

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
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":47858,"county":["Clay","Sullivan","Vigo"]}}
CURL EXAMPLE
Sample Request:
                                    
curl -X GET 'https://service.zipapi.us/zipcode/county/47858?X-API-KEY=your_api_key'
Sample Response: 
    
{"status":true,"data":{"zipcode":47858,"county":["Clay","Sullivan","Vigo"]}}
PYTHON EXAMPLE
Sample Request:
                                    
import requests
r = requests.get("https://service.zipapi.us/zipcode/county/47858?X-API-KEY=your_api_key")
print(r.text)
Sample Response: 
    
{"status":true,"data":{"zipcode":47858,"county":["Clay","Sullivan","Vigo"]}}
JAVASCRIPT EXAMPLE
Sample Request:
                        

    var clientKey = 'Your js key';
    var url = "https://service.zipapi.us/zipcode/county/47858?X-API-KEY=" + clientKey;


    var xhttp = new XMLHttpRequest();


    xhttp.onreadystatechange = function() {

        if (this.readyState == 4) {

            document.getElementById("demo").innerHTML = this.responseText;
        }


    };

    xhttp.open("GET", url, true);
    xhttp.send();
Sample Response: 
    
{"status":true,"data":{"zipcode":47858,"county":["Clay","Sullivan","Vigo"]}}

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

Code Samples
PHP EXAMPLE
Sample Request:
                
//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_RETURNTRANSFER, 1);
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 EXAMPLE
Sample Request:
                                    
curl -X GET 'https://service.zipapi.us/zipcode/zips?X-API-KEY=your_api_key&city=Beverly Hills&state=CA'
Sample Response: 
    
{"status":true,"data":["90209","90210","90211","90212","90213"]}
PYTHON EXAMPLE
Sample Request:
                                    
import requests
r = requests.get("https://service.zipapi.us/zipcode/zips?X-API-KEY=your_api_key&city=Beverly Hills&state=CA")
print(r.text)
Sample Response: 
    
{"status":true,"data":["90209","90210","90211","90212","90213"]}
JAVASCRIPT EXAMPLE
Sample Request:
                        

    var clientKey = 'Your js key';
    var url = "https://service.zipapi.us/zipcode/zips?X-API-KEY=" + clientKey + "&city=Beverly Hills&state=CA";


    var xhttp = new XMLHttpRequest();


    xhttp.onreadystatechange = function() {

        if (this.readyState == 4) {

            document.getElementById("demo").innerHTML = this.responseText;
        }


    };

    xhttp.open("GET", url, true);
    xhttp.send();
Sample Response: 
    
{"status":true,"data":["90209","90210","90211","90212","90213"]}

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.

Code Samples
PHP EXAMPLE
Sample Request:
                
//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_RETURNTRANSFER, 1);
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 EXAMPLE
Sample Request:
                                    
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"}}
PYTHON EXAMPLE
Sample Request:
                                    
import requests
r = requests.get("https://service.zipapi.us/zipcode/distance?X-API-KEY=your_api_key&zip1=46220&zip2=90210")
print(r.text)
Sample Response: 
    
{"status":true,"data":{"distance":1816.8075364700221,"unit":"mi"}}
JAVASCRIPT EXAMPLE
Sample Request:
                        

    var clientKey = 'Your js key';
    var url = "https://service.zipapi.us/zipcode/distance?X-API-KEY=" + clientKey + "&zip1=46220&zip2=90210";


    var xhttp = new XMLHttpRequest();


    xhttp.onreadystatechange = function() {

        if (this.readyState == 4) {

            document.getElementById("demo").innerHTML = this.responseText;
        }


    };

    xhttp.open("GET", url, true);
    xhttp.send();
Sample Response: 
    
{"status":true,"data":{"distance":1816.8075364700221,"unit":"mi"}}

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.

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

$curl = curl_init();

// OPTIONS:
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
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"
        }
    ]
}

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/90210/?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

Code Samples
PHP EXAMPLE
Sample Request:
                        
//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_RETURNTRANSFER, 1);
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 EXAMPLE
Sample Request:
                                    
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"}}
PYTHON EXAMPLE
Sample Request:
                                    
import requests

r = requests.get("https://service.zipapi.us/population/zipcode/90210?X-API-KEY=your_api_key&fields=male_population,female_population")
print(r.text)
Sample Response: 
                        
{"status":true,"data":{"population":"21741","male_population":"10292","female_population":"11449"}}
JAVASCRIPT EXAMPLE
Sample Request:
                        

    var clientKey = 'Your js key';
    var url = "https://service.zipapi.us/population/zipcode/90210?X-API-KEY=" + clientKey + "&fields=male_population,female_population";


    var xhttp = new XMLHttpRequest();


    xhttp.onreadystatechange = function() {

        if (this.readyState == 4) {

            document.getElementById("demo").innerHTML = this.responseText;
        }


    };

    xhttp.open("GET", url, true);
    xhttp.send();
Sample Response: 
                        
{"status":true,"data":{"population":"21741","male_population":"10292","female_population":"11449"}}