Google Maps API

Geocoding Strategies

Content

  1. Introduction
  2. Quota Considerations
  3. Caching Considerations
  4. When to use Client-Side Geocoding
  5. When to use Server-Side Geocoding
  6. Conclusion

Introduction

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

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

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
  });

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

import urllib2

address="1600+Amphitheatre+Parkway,+Mountain+View,+CA"
url="http://maps.googleapis.com/maps/api/geocode/json?address=%s&sensor=false" % address

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.

Quota Considerations

Server-side geocoding through the Geocoding Web Service has a quota of 2,500 requests per IP per day, so all requests in one day count against the quota. In addition, the Web Service is rate-limited, so that requests that come in too quickly result in blocking. Client-side geocoding through the browser is rate limited per map session, so the geocoding is distributed across all your users and scales with your userbase. Geocoding quotas and rate limits drive the strategies outlined in this article.

When running client-side geocode requests at periodic intervals, such as on a mobile app, your requests may be subject to blocking if all of your users are making requests at the same time (e.g. 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.

In Google Maps API for Business, quotas are tied to client IDs, which provide much higher quotas. To learn more about Maps API for Business quotas and error handling, we recommend reviewing our article, Usage Limits for Google Maps API Web Services. If you're still running into quota limits using the Google Maps API for Business, file a support request here: http://www.google.com/enterprise/portal/.

Caching Considerations

The Google Maps API allows you to cache geocodes (i.e. store them on your server for a limited period). Caching can be useful if you have to repeatedly look up the same address. However, there are two important things to keep in mind.

  1. The Google Maps API Terms of Service allow you to use geocodes derived from the service on Google Maps or Google Earth only. You may not sell or distribute them in other fashion.
  2. Geocoding changes often 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.

The Google Maps API for Flash requires the use of API keys. Many people mistakenly think quotas are tied to keys. However, keys don't affect your geocoding quota at all. Registering for a new key won't help. Quota is solely tied to IP addresses. Therefore a new key won't give you any more quota at a particular IP address.

When to Use Client-Side Geocoding

The basic answer is "almost always." As geocoding limits are per user session, there is no risk that your application will reach a global limit as your userbase grows. Client-side geocoding will not face a quota limit unless you perform a batch of geocoding requests within a user session. Therefore, running client-side geocoding, you generally don't have to worry about your quota.

Two basic architectures for client-side geocoding exist.

  • Run the geocoding and 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, but doesn't give you any sense of what your users are doing.

  • Run the geocode in the browser and then send it to the server. For instance, the user enters an address. 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. This cache allows you to optimize even more. You can even query the server with the address, see if you have a recently cached geocode for it, and if you do, use that. If you don't, then return no result to the browser, and let it geocode the result and send it back to the server to 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. This usually happens when you get a dataset that comes separately from user input, for instance if you have a fixed, finite, and known set of addresses that need geocodes. Server-side geocoding can also be useful as a back-up for when client-side geocoding fails.

You should be wary of relying on server-side geocoding. The 2,500 request limit is per IP address. All people using your application are sharing your single server. If you are processing requests that come in from a large number of clients, you could easily overload your quota for the day, or even the queries per second from the same IP address. Also, many cloud computing infrastructures, such as Google App Engine or Amazon Web Services, share IP addresses between different applications. Your requests may run up against quota used by other applications wholly outside your control.

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 that geocode 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 geocode to the original application.
  • Sometime later, the geocode is used to display data on a Google Map.

Conclusion

In general, a combination of client-side geocoding and caching will serve most of your needs, and the generous geocoding limits in place in the JavaScript API will be more than most applications need. You should be careful implementing server-side only, as you're very likely to run into quota issues if you geocode too fast or too much. If after designing your site, you're still running into problems with quota, you may consider a Maps API for Business license. Check out the Google Earth and Maps Enterprise site for more information on the differences and how to get started.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.