Live API

Register for Application Key

Free Key

More than 50 Requests/Hour

Low Cost Upgrades

To use on your site

Set up JavaScript Access

This example auto-fills the city and state after a zip code is entered.

JavaScript Code

<script type="text/javascript">//<![CDATA[
	$(function() {
		// IMPORTANT: Fill in your client key
		var clientKey = "js-9qZHzu2Flc59Eq5rx10JdKERovBlJp3TQ3ApyC4TOa3tA8U7aVRnFwf41RpLgtE7";
		
		var cache = {};
		var container = $("#example1");
		var errorDiv = container.find("div.text-error");
		
		/** Handle successful response */
		function handleResp(data)
		{
			// Check for error
			if (data.error_msg)
				errorDiv.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
				errorDiv.empty();
				
				// Check cache
				if (zipcode in cache)
				{
					handleResp(cache[zipcode]);
				}
				else
				{
					// Build url
					var url = "http://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)
								errorDiv.text(json.error_msg);
						}
						else
							errorDiv.text('Request failed.');
					});
				}
			}
		}).trigger("change");
	});
//]]></script>

This example determines the distance between two zip code that are entered.

JavaScript Code

<script type="text/javascript">//<![CDATA[
	$(function() {
		// IMPORTANT: Fill in your client key
		var clientKey = "js-9qZHzu2Flc59Eq5rx10JdKERovBlJp3TQ3ApyC4TOa3tA8U7aVRnFwf41RpLgtE7";
		
		var cache = {};
		var container = $("#example2");
		var errorDiv = container.find("div.text-error");
		
		/** Handle successful response */
		function handleResp(data)
		{
			// Check for error
			if (data.error_msg)
				errorDiv.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
				errorDiv.empty();
				
				// Check cache
				var cacheKey = zipcode1 + '-' + zipcode2;
				if (cacheKey in cache)
				{
					handleResp(cache[cacheKey]);
				}
				else
				{
					// Build url
					var url = "http://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)
								errorDiv.text(json.error_msg);
						}
						else
							errorDiv.text('Request failed.');
					});
				}
			}
		}).trigger("change");
	});
//]]></script>

Use this API to determine the distance between two zip codes. Send a GET request to http://www.zipcodeapi.com/rest/<api_key>/distance.<format>/<zip_code1>/<zip_code2>/<units>.

Use this API to find all zip codes within a given radius of a zip code. Send a GET request to http://www.zipcodeapi.com/rest/<api_key>/radius.<format>/<zip_code>/<distance>/<units>.

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

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 http://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 zip code. The JSON and XML responses will allow contain alternative acceptable city names for a location. Send a GET request to http://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, longitude, and time zone information for multiple zip codes. The JSON and XML responses will allow contain alternative acceptable city names for a location. Send a GET request to http://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 city. Send a GET request to http://www.zipcodeapi.com/rest/<api_key>/city-zips.<format>/<city>/<state>.

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 http://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 register your application to use the API. It's simple and 100% free for up to 50 requests per hour. You can view our Usage Plans for information on usage above 50 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.