You're all set!

To start developing, please head over to our developer documentation.

Activate the Google Maps Geocoding API

To get you started we'll guide you through the Google Developers Console to do a few things first:

  1. Create or choose a project
  2. Activate the Google Maps Geocoding API
  3. Create appropriate keys
Continue

Geocoding Strategies

Geocoding is the process of converting addresses ("1600 Amphitheatre Parkway, Mountain View, CA") to geographic coordinates (37.423021, -122.083739), which you can use to place markers or position the map. The Google Maps APIs provide two approaches to geocoding:

  • Client-side geocoding, which is executed in the browser, generally in response to user action. The Google Maps JavaScript API provides classes that make the requests for you. This approach is described in the Google Maps JavaScript API documentation.
  • HTTP server-side geocoding, which allows your server to directly query Google's servers for geocodes. The Google Maps Geocoding API is the web service that provides this functionality. Typically, you integrate this service with other code that is running server-side. Server-side geocoding is described in the Google Maps Geocoding API documentation.

Examples of client-side and server-side geocoding

Here is a sample of client-side geocoding which takes an address, geocodes it, moves the center of the map to that location, and adds a map marker there:

geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': address }, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

For more examples, see the Google Maps JavaScript API documentation.

Here is an example using Python to do a server-side geocoding request:

import urllib2

address="1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key="my-key-here"
url="https://maps.googleapis.com/maps/api/geocode/json?address=%s&key=%s" % (address, key)

response = urllib2.urlopen(url)
jsongeocode = response.read()

This produces a JSON object with the following content:

{
  "status": "OK",
  "results": [ {
    "types": street_address,
    "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    "address_components": [ {
      "long_name": "1600",
      "short_name": "1600",
      "types": street_number
    }, {
      "long_name": "Amphitheatre Pkwy",
      "short_name": "Amphitheatre Pkwy",
      "types": route
    }, {
      "long_name": "Mountain View",
      "short_name": "Mountain View",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "San Jose",
      "short_name": "San Jose",
      "types": [ "administrative_area_level_3", "political" ]
    }, {
      "long_name": "Santa Clara",
      "short_name": "Santa Clara",
      "types": [ "administrative_area_level_2", "political" ]
    }, {
      "long_name": "California",
      "short_name": "CA",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    }, {
      "long_name": "94043",
      "short_name": "94043",
      "types": postal_code
    } ],
    "geometry": {
      "location": {
        "lat": 37.4220323,
        "lng": -122.0845109
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "southwest": {
          "lat": 37.4188847,
          "lng": -122.0876585
        },
        "northeast": {
          "lat": 37.4251799,
          "lng": -122.0813633
        }
      }
    }
  } ]
}

The server-side geocoder also provides an XML format as an alternative to JSON. For more examples, see the Google Maps Geocoding API documentation and the client libraries for Python and other languages.

Quota considerations

Geocoding quotas and rate limits drive the strategies outlined in this document.

When using the standard plan, all geocoding requests, whether client-side through the browser or server-side through the Google Maps Geocoding API web service, have a quota of 2,500 requests per day. All requests in one day count against the quota for your project. To access higher daily quotas, enable pay-as-you-go billing as described in the guide to usage limits.

In addition to daily quota limits, the geocoding service is rate limited to 50 QPS (queries per second), calculated as the sum of client-side and server-side queries.

When running client-side geocoding requests at periodic intervals, such as in a mobile app, your requests may return errors if all of your users are making requests at the same time (for example, all at the same second of every minute). To avoid this, consider one of the following:

  • Use a caching strategy.
  • Introduce random intervals to your requests (jitter). Ensure requests are random across your entire userbase.
  • If developing for Android, use an inexact repeating alarm.
  • If developing for Android, select an appropriate location strategy.

For Google Maps APIs Premium Plan customers, the APIs offer higher daily quotas. To learn more about Google Maps APIs Premium Plan quotas, see the guide to Premium Plan usage rates and limits. If you're still running into quota limits using the Google Maps APIs Premium Plan, file a support request on the Google for Work Support Portal.

Caching considerations

The Google Maps APIs Terms of Service allow you to cache geocodes (that is, store them on your server for a limited period). Caching can be useful if you have to repeatedly look up the same address. However, keep in mind that geocoding results change as our data gets more and more accurate. So even if you have cached data, you should refresh it periodically, to make sure you are getting the best geocodes for your locations.

When to use client-side geocoding

The short answer is "almost always." The reasons are:

  • Client-side request and response provide a faster, more interactive experience for users.
  • A client-side request can include information that improves geocoding quality: user language, region, and viewport.

In particular, client-side geocoding is best when geocoding addresses based on input from the user.

There are two basic architectures for client-side geocoding:

  • Do the geocoding and the display entirely in the browser. For instance, the user enters an address on your page. Your application geocodes it. Then your page uses the geocode to create a marker on the map. Or your app does some simple analysis using the geocode. No data is sent to your server. This reduces load on your server.
  • Do the geocoding in the browser and then send it to the server. For instance, the user enters an address on your page. Your application geocodes it in the browser. The app then sends the data to your server. The server responds with some data, such as nearby points of interest. This allows you to customize a response based on your own data, and also to cache the geocode if you want. The caching allows you to optimize even more. For example, you can query the server with the address, to see if you have a recently cached geocode for it. If you don't have a match in the cache, then return no result to the browser, and let it geocode the result and send it back to the server for caching.

When to use server-side geocoding

Server-side geocoding is best used for applications that require you to geocode addresses without input from a client. A common example is when you get a dataset that comes independently of user input, for instance if you have a fixed, finite, and known set of addresses that need geocoding. Server-side geocoding can also be useful as a backup for when client-side geocoding fails.

Some possible concerns are an unnecessary increase in latency for the user, and geocoding results of a lesser quality than client-side because less information is available in the request.

The basic architecture for a server-side geocoding application is the following:

  • A server-based application sends an address to the server's geocoding script.
  • The script checks the cache to see if the address has recently been geocoded.
  • If it has, the script returns the result to the original application.
  • If it has not, the script sends a geocoding request to Google. Once it has a result, it caches it, and then returns the result to the original application.

Conclusion

In general, a combination of client-side geocoding and caching serves most of your needs. If you run into problems with quota, consider enabling billing or purchasing a Premium Plan license.

Send feedback about...

Google Maps Geocoding API
Google Maps Geocoding API
Need help? Visit our support page.