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.
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 register your application 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. |