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.

Error

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.

<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.

<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.

<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 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.

You are watching: Zip Code API Documentation. Info created by GBee English Center selection and synthesis along with other related topics.