Live API

Get Free Application Key

Background image

Low Cost Upgrades

Background image

Set up JavaScript Access

Background image

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.

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-target and data-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-target with 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 input
  • cityInput (Type: HTMLInputElement|undefined) - City input
  • stateInput (Type: HTMLInputElement|HTMLSelectElement|undefined) - State input or select
  • countryInput (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 Promise that 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 this API to determine the distance between two US zip codes. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/distance.<format>/<zip_code1>/<zip_code2>/<units>.

Use this API to determine the distance between two CA postal codes. Send a GET request to https://www.zipcodeapi.com/rest/v2/CA/<api_key>/distance.<format>/<postal_code1>/<postal_code2>/<units>.

Use this API to determine the distance between one US zip code and multiple other US zip codes. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/multi-distance.<format>/<zip_code>/<other_zip_codes>/<units>.

Each zip code provided will count as a separate request. For example, if you send 5 zip codes, you will be charged for 5 requests. Any zip code not found will not be included in the response.

Use this API to find all US zip codes within a given radius of a zip code. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/radius.<format>/<zip_code>/<distance>/<units>. The radius is capped at 500 miles unless the minimal option is used or you have the unlimited subscription.

If you only want the zip code in the response, you can add a GET parameter of minimal to the url. For example, https://www.zipcodeapi.com/rest/<api_key>/radius.csv/08057/5/miles?minimal.

Use this API to find all Canadian postal codes within a given radius of a postal code. Send a GET request to https://www.zipcodeapi.com/rest/v2/CA/<api_key>/radius.<format>/<postal_code>/<distance>/<units>. The radius is capped at 805 km unless the minimal option is used or you have the unlimited subscription.

If you only want the postal code in the response, you can add a GET parameter of minimal to the url. For example, https://www.zipcodeapi.com/rest/v2/CA/<api_key>/radius.json/A1A1A1/5/mile?minimal.

If you only want the postal code and distance in the response, you can add a GET parameter of simple to the url. For example, https://www.zipcodeapi.com/rest/v2/CA/<api_key>/radius.json/A1A1A1/5/mile?simple. The JSON will include two keys for postal_codes and distances. This is formatted this way to reduce bandwidth consumption. The first element in the postal_codes has a distance matching the first element of the distances, the second element in the postal_codes has a distance matching the second element of the distances, and so forth.

The response is limited to the nearest 250 postal codes.
You can increase the limit up to 1,500 if you use the minimal option by setting limit=1500 in the URL.
You can increase the limit up to 50,000 if you use the simple option by setting limit=50000 in the URL.

Use this API to find all US zip codes within a given radius of multiple zip codes. Send a POST request to https://www.zipcodeapi.com/rest/<api_key>/multi-radius.<format>/<distance>/<units>. The radius is capped at 500 miles.

You may only send one of zip_codes or addrs. Both of these fields are POST variables and have maximum of 100 lines. For zip_codes, each line should be a zip code. For addrs, each line should be an address such as “123 Main St., Moorestown NJ 08057”. We will make a best guess effort to extract a zip code from the addresses you provide.

Each line is charged as a separate request.

Use this API to send a list of zip codes and return all pairs where the distance between the zip codes is less than a given distance. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/match-close.<format>/<zip_codes>/<distance>/<units>.

Use this API to find out the city, state, latitude, longitude, and time zone information for a US zip code. The JSON and XML responses will allow contain alternative acceptable city names for a location. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/info.<format>/<zip_code>/<units>.

Click here for an example of auto-filling city and state in a form when a zip code is entered.

Use this API to find out the city, state, latitude, and longitude information for a CA postal code. The JSON and XML responses will allow contain alternative acceptable city names for a location. Send a GET request to https://www.zipcodeapi.com/rest/v2/CA/<api_key>/info.<format>/<postal_code>/<units>.

Click here for an example of auto-filling city and state in a form when a postal code is entered.

Use this API to find out the city, state, latitude, longitude, and time zone information for multiple US zip codes. The JSON and XML responses will allow contain alternative acceptable city names for a location. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/multi-info.<format>/<zip_code>/<units>.

Each zip code provided will count as a separate request. For example, if you send 5 zip codes, you will be charged for 5 requests. Any zip code not found will not be included in the response.

Use this API to find out possible zip codes for a US city. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/city-zips.<format>/<city>/<state>.

Use this API to find out possible postal codes for a Canadian city. Send a GET request to https://www.zipcodeapi.com/rest/v2/CA/<api_key>/city-postal-codes.<format>/<city>/<province>.

Use this API to find out zip codes in a US state. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/state-zips.<format>/<state>.

This API is charged as multiple requests. Every 10 zip codes returned are charged as 1 request. For example, if the state you select returns 200 zip codes, you will be charged for 20 requests.

Use this API to build the SQL WHERE clause to use in your own database to search by latitude/longitude in a radius. Send a GET request to https://www.zipcodeapi.com/rest/<api_key>/radius-sql.<format>/<lat>/<long>/<lat_long_units>/<distance>/<units>/<lat_field_name>/<long_field_name>/<precision>. You specify the latitude and longitude of center point, the distance/radius from this location, the field names used in your database for latitude and longitude, and a precision. The higher the precision, the more detailed the SQL string will be and the more accurate the results will be. A precision of 2 gives decent results for short distances. Larger distances might require a higher precision. To make your database queries efficient, you should create an index on the latitude/longitude pair in your database.

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.