Have you ever come across a web form which asks for your ZIP code and then pre-fills your city and state in for you? I love these types of seemingly small interactions which can end up saving people time and remove some human error. In this post I will show you how to use Google Maps APIs to take a ZIP code and turn it into a city and state.

Update 2024: This still works 8 years later. Be sure to get an API key which is now a required parameter for geocoding lookups. The geocoding api has a generous free tier, but it is not unlimited. For information on setting up an API key visit the Google Cloud Platform.

Editor’s Note: This post was first published in 2016, since then Google has released the Places Autocomplete API, which would be a more appropriate use-case for pre-filling a full address form. There are still other valid reasons to look up city/state using ZIP code, and if you have one, read on.

ZIP code lookup

In order to get the city and state based off a ZIP code, we are going to want to use Google’s Geocoding API. The request is actually very simple once we have an API key. You can pass in all kinds of data in the address field, so be sure to read the documentation, but simply passing the ZIP code gives us what we need. The request format is: http://maps.googleapis.com/maps/api/geocode/json?address=ZIP_CODE&key=YOUR_API_KEY. The response contains a lot of information, including for our purposes, the matching localities. So we can, for example, see that 92101 is the postal code for San Diego, California.

request:

GET https://maps.googleapis.com/maps/api/geocode/json?address=92101&key=YOUR_API_KEY

response:

You can read more about the many features of Google’s geocoding API on their documentation page. If you are comfortable with parsing JSON, you probably have found what you were looking for. If you want an example of how to use this data to actually fill in a form, read on.

Simple Form

How can we utilize Google’s Geocode API response to pre-populate an address form?

Let’s start with the basic HTML form:

Add a bit of Javascript

We can use javascript to watch for a change on the ZIP code field, and make a request to Google’s API to find out the city and state. We will use that response to pre-fill the city and state fields. This example assumes you are using jQuery.

The form will now automatically fill in your city and state fields once the zip code field is filled in.

We aren’t quite done. What about ZIP codes that encompass multiple cities? These are more common than I would have believed. Take the reponse for a lookup on 60047 for example, there are 4 different cities listed in the “postcode_localities” field.

{ "results" :[
  { ...
    "postcode_localities" : [ "Hawthorn Woods", "Kildeer", "Lake Zurich", "Long Grove" ],
    ...
  }
]}

The only thing worse than the form not pre-filling itself, is having it pre-fill itself incorrectly.

With a slightly modified function to fill in the form fields, we can test for multiple “postcode_localities” and turn the city text input field into select input and pre-fill it with the city from the “address_components”

If you want to see the form and javascript code in action, visit the demo page and take a look at the full example Code on Github.