Live API
Important! Our API only supports US zip codes and Canadian postal codes. You must use the appropriate endpoint for the country you desire.
When working with CA postal codes in URLs, you must either remove the space or URL encode it (e.g. with a plus sign). For example, A0A 1A0 should appear in the URL as A0A1A0 or A0A+1A0.
The data for the Canadian API is sourced from the GeoNames data sets, which are licensed under the Creative Commons Attribution 4.0 License.
OpenAPI Specifications
Our OpenAPI v3 specifications file can be found at https://www.zipcodeapi.com/openapi.yaml.
You can include our JavaScript on a website and get started with the Zip Code API in minutes.
Start by adding our JavaScript file (make sure to enter your client key, which starts with js-).
<script defer="defer" src="https://assets.zipcodeapi.com/zipcodeapi-1.0.js" data-key="ENTER_YOUR_CLIENT_KEY"></script>
Setting Up City/State Auto-Fill
- You can fill in city and state inputs by tagging a zip code input with
data-city-targetanddata-state-target. - The value can be any selector supported by
querySelector. - Often, this will be an ID, such as
#myCityInput. -
If you allow country selection, you can add
data-country-targetwith a selector for the country input. By doing so, the library will only make API calls if the country is set to United States (the value must be "US" or "United States").
Example Source Code
<script defer="defer" src="https://assets.zipcodeapi.com/zipcodeapi-1.0.js" data-key="ENTER_YOUR_CLIENT_KEY"></script>
<!-- If you support multiple countries, put the country input before the zip code -->
<select name="country" id="country">
<option value="">--- Select a Country ---</option>
<option value="US" selected="selected">United States</option>
</select>
<!-- Tag the zip code input with data-*-target="..." attributes with HTML selectors for the city, state, and country -->
<input name="zipcode" data-city-target="#city" data-state-target="#state" data-country-target="#country" placeholder="Zip code" />
<!-- Put the city and start after zip code so they are filled in prior to users reaching them -->
<input name="city" id="city" placeholder="City" />
<select name="state" id="state">
<option value=""></option>
<option value="AK">AK - Alaska</option>
<option value="AL">AL - Alabama</option>
<option value="AR">AR - Arkansas</option>
<option value="AS">AS - American Samoa</option>
<option value="AZ">AZ - Arizona</option>
<option value="CA">CA - California</option>
<option value="CO">CO - Colorado</option>
<option value="CT">CT - Connecticut</option>
<option value="DC">DC - District of Columbia</option>
<option value="DE">DE - Delaware</option>
<option value="FL">FL - Florida</option>
<option value="GA">GA - Georgia</option>
<option value="GU">GU - Guam</option>
<option value="HI">HI - Hawaii</option>
<option value="IA">IA - Iowa</option>
<option value="ID">ID - Idaho</option>
<option value="IL">IL - Illinois</option>
<option value="IN">IN - Indiana</option>
<option value="KS">KS - Kansas</option>
<option value="KY">KY - Kentucky</option>
<option value="LA">LA - Louisiana</option>
<option value="MA">MA - Massachusetts</option>
<option value="MD">MD - Maryland</option>
<option value="ME">ME - Maine</option>
<option value="MI">MI - Michigan</option>
<option value="MN">MN - Minnesota</option>
<option value="MO">MO - Missouri</option>
<option value="MP">MP - Northern Mariana Islands</option>
<option value="MS">MS - Mississippi</option>
<option value="MT">MT - Montana</option>
<option value="NC">NC - North Carolina</option>
<option value="ND">ND - North Dakota</option>
<option value="NE">NE - Nebraska</option>
<option value="NH">NH - New Hampshire</option>
<option value="NJ">NJ - New Jersey</option>
<option value="NM">NM - New Mexico</option>
<option value="NV">NV - Nevada</option>
<option value="NY">NY - New York</option>
<option value="OH">OH - Ohio</option>
<option value="OK">OK - Oklahoma</option>
<option value="OR">OR - Oregon</option>
<option value="PA">PA - Pennsylvania</option>
<option value="PR">PR - Puerto Rico</option>
<option value="RI">RI - Rhode Island</option>
<option value="SC">SC - South Carolina</option>
<option value="SD">SD - South Dakota</option>
<option value="TN">TN - Tennessee</option>
<option value="TT">TT - Trust Territories</option>
<option value="TX">TX - Texas</option>
<option value="UT">UT - Utah</option>
<option value="VA">VA - Virginia</option>
<option value="VI">VI - Virgin Islands</option>
<option value="VT">VT - Vermont</option>
<option value="WA">WA - Washington</option>
<option value="WI">WI - Wisconsin</option>
<option value="WV">WV - West Virginia</option>
<option value="WY">WY - Wyoming</option>
</select>
Manual Form Initialization
You can also call
ZipCodeAPI.initInput(zipcodeInput, cityInput, stateInput, countryInput) to initialize a form without data attributes.
zipcodeInput(Type:HTMLInputElement) - Zip code inputcityInput(Type:HTMLInputElement|undefined) - City inputstateInput(Type:HTMLInputElement|HTMLSelectElement|undefined) - State input or selectcountryInput(Type:HTMLInputElement|HTMLSelectElement|undefined) - Country input or select
JavaScript API to Get Zip Code Info
- You can call
ZipCodeAPI.getZipCode(zipcode)directly to get zip code information from the “US Zip Code to Location Information” API. - This returns a
Promisethat will resolve to the zip code information or null if it’s not found.
This example auto-fills the city and state after a zip code is entered.
If you use the example JavaScript, you must update it with your client key (starts with js-) and update it to match the DOM elements on your website.
JavaScript Code
<script>//<![CDATA[
window.addEventListener('DOMContentLoaded', function() {
// IMPORTANT: Fill in your client key
var clientKey = "FILL_IN_CLIENT_KEY";
var cache = {};
var container = $("#example1");
var errorElem = container.find(".label-error");
/** Handle successful response */
function handleResp(data)
{
// Check for error
if (data.error_msg)
errorElem.text(data.error_msg);
else if ("city" in data)
{
// Set city and state
container.find("input[name='city']").val(data.city);
container.find("input[name='state']").val(data.state);
}
}
// Set up event handlers
container.find("input[name='zipcode']").on("keyup change", function() {
// Get zip code
var zipcode = $(this).val().substring(0, 5);
if (zipcode.length == 5 && /^[0-9]+$/.test(zipcode))
{
// Clear error
errorElem.empty();
// Check cache
if (zipcode in cache)
{
handleResp(cache[zipcode]);
}
else
{
// Build url
var url = "https://www.zipcodeapi.com/rest/"+clientKey+"/info.json/" + zipcode + "/radians";
// Make AJAX request
$.ajax({
"url": url,
"dataType": "json"
}).done(function(data) {
handleResp(data);
// Store in cache
cache[zipcode] = data;
}).fail(function(data) {
if (data.responseText && (json = $.parseJSON(data.responseText)))
{
// Store in cache
cache[zipcode] = json;
// Check for error
if (json.error_msg)
errorElem.text(json.error_msg);
}
else
errorElem.text('Request failed.');
});
}
}
}).trigger("change");
});
//]]></script>
This example auto-fills the city and province after a Canadian postal code is entered.
If you use the example JavaScript, you must update it with your client key (starts with js-) and update it to match the DOM elements on your website.
JavaScript Code
<script>//<![CDATA[
window.addEventListener('DOMContentLoaded', function() {
// IMPORTANT: Fill in your client key
var clientKey = "FILL_IN_CLIENT_KEY";
var cache = {};
var container = $("#caPostalAutofill");
var errorElem = container.find(".label-error");
/** Handle successful response */
function handleResp(data)
{
// Check for error
if (data.error_msg)
errorElem.text(data.error_msg);
else if ("city" in data)
{
// Set city and province
container.find("input[name='caCity']").val(data.city);
container.find("input[name='caProvince']").val(data.province);
}
}
// Set up event handlers
container.find("input[name='caPostalCode']").on("keyup change", function() {
// Get postal code
var postalCode = $(this).val().toUpperCase();
if (/^[A-Z][0-9][A-Z] ?[0-9][A-Z][0-9]$/.test(postalCode))
{
// Clear error
errorElem.empty();
// Check cache
if (postalCode in cache)
handleResp(cache[postalCode]);
else
{
// Build url removing space in postal code
var url = "https://www.zipcodeapi.com/rest/v2/CA/" + clientKey + "/info.json/" + postalCode.replace(/ /g, "") + "/radians";
// Make AJAX request
$.ajax({
"url": url,
"dataType": "json"
}).done(function(data) {
handleResp(data);
// Store in cache
cache[postalCode] = data;
}).fail(function(data) {
if (data.responseText && (json = $.parseJSON(data.responseText)))
{
// Store in cache
cache[postalCode] = json;
// Check for error
if (json.error_msg)
errorElem.text(json.error_msg);
}
else
errorElem.text('Request failed.');
});
}
}
}).trigger("change");
});
//]]></script>
This example determines the distance between two zip code that are entered.
JavaScript Code
<script>//<![CDATA[
window.addEventListener('DOMContentLoaded', function() {
// IMPORTANT: Fill in your client key
var clientKey = "FILL_IN_CLIENT_KEY";
var cache = {};
var container = $("#example2");
var errorElem = container.find(".label-error");
/** Handle successful response */
function handleResp(data)
{
// Check for error
if (data.error_msg)
errorElem.text(data.error_msg);
else if ("distance" in data)
{
// Show div
container.find("div.distance").show()
// Set distance
.find("span.distance").text(data.distance + " miles");
}
}
// Set up event handlers
container.find("input[name='zipcode1'],input[name='zipcode2']").on("keyup change", function() {
// Get zip code
var zipcode1 = $("input[name='zipcode1']").val().substring(0, 5);
var zipcode2 = $("input[name='zipcode2']").val().substring(0, 5);
if (zipcode1.length == 5 && /^[0-9]+$/.test(zipcode1) && zipcode2.length == 5 && /^[0-9]+$/.test(zipcode2))
{
// Clear error
errorElem.empty();
// Check cache
var cacheKey = zipcode1 + '-' + zipcode2;
if (cacheKey in cache)
{
handleResp(cache[cacheKey]);
}
else
{
// Build url
var url = "https://www.zipcodeapi.com/rest/"+clientKey+"/distance.json/" + zipcode1 + "/" + zipcode2 + "/mile";
// Make AJAX request
$.ajax({
"url": url,
"dataType": "json"
}).done(function(data) {
handleResp(data);
// Store in cache
cache[cacheKey] = data;
}).fail(function(data) {
if (data.responseText && (json = $.parseJSON(data.responseText)))
{
// Store in cache
cache[cacheKey] = json;
// Check for error
if (json.error_msg)
errorElem.text(json.error_msg);
}
else
errorElem.text('Request failed.');
});
}
}
}).trigger("change");
});
//]]></script>
Use of this API is subject to our Terms of Use. You must create an account to use the API. It's simple and 100% free for up to 10 requests per hour. You can view our Usage Plans for information on usage above 10 requests/hr.
To prevent abuse, the API key on this page is periodically regenerated. If your request failed with an error message indicating that the API key is not found, please reload the page and try again. We also will intentionally return incorrect values for this demo if our system detects abuse.
Error Codes
Error codes are returned via the HTTP response code.
| Status Code | Reason |
|---|---|
| 400 | The request format was not correct. |
| 401 | The API key was not found, was not activated, or has been disabled. |
| 404 | A zip code you provided was not found. |
| 429 | The usage limit for your application has been exceeded for the hour time period. |