Google Maps API

Upgrading Your Geocoding API Application To v3

Samuel Baroman, Google Enterprise Support Team
February 2013

This document is intended for developers migrating to version 3 ("v3") of the Geocoding API. Version 2 ("v2") of the Geocoding API was officially deprecated on 8 March 2010 and has now been turned down. As of 9 September 2013 the v2 API will no longer work.

Overview

The v3 Geocoding API is a web service intended for processing a set of addresses that are known in advance. For example, you can geocode a list of store addresses contained in a database, or find the address for a given latitude and longitude (reverse-geocoding).

Before migrating your application to the v3 Geocoding API, you should first consider if your application is best suited to utilize the web service, or is better served by using a client-side approach (e.g., via the JavaScript Geocoder class). The latter is designed for handling user-submitted geocode requests — traffic that is unpredictable and sent in real time.

For more guidance on geocoding approaches, please see our article on Geocoding Strategies.

What’s new in Version 3 of the Geocoding API

New endpoint

The v3 Geocoder uses a different URL endpoint:

http://maps.googleapis.com/maps/api/geocode/output?parameters

Where output can be specified as json or xml.

Developers switching from v2 may be using a legacy hostname — either maps.google.com, or maps-api-ssl.google.com if using SSL. You should migrate to the new hostname: maps.googleapis.com. This hostname can be used both over both HTTPS and HTTP.

New URL parameters

Please see the Geocoding API documentation for the entire list of required and optional URL parameters.

Client ID required for Maps for Business customers

In addition to the above parameters, Maps API for Business customers are required to supply a client ID parameter and a digital signature to use the Geocoding API. The client ID links your Maps API for Business account to the Geocoding API request.

A digital signature is generated by signing your Geocode URLs using an encryption algorithm and your private, cryptographic key. This adds an additional layer of security and protects your client ID from being compromised. More on URL signing can be found in our YouTube tutorial as well as in our documentation. If you don’t know, or can't remember, your cryptographic key, you can recover it by filing a support case in the Google Enterprise Support Portal.

Flatter Response

The v2 Geocoding API returns a nested, hierarchical response, whereas v3 returns a flat response which is much easier to parse. For example, it is required in v2 to traverse the nested structure of AddressDetails in order to fetch a street:

(response truncated)
{
  ...
  "AddressDetails": {
    "Accuracy" : 8,
    "Country" : {
      "AdministrativeArea" : {
        "AdministrativeAreaName" : "CA",
        "Locality" : {
          "LocalityName" : "Mountain View",
          "PostalCode" : {
            "PostalCodeNumber" : "94043"
          },
          "Thoroughfare" : {
            "ThoroughfareName" : "1600 Amphitheatre Parkway"
          }
        }
      },
      "CountryName" : "USA",
      "CountryNameCode" : "US"
    }
  },
  ...
}

In v3, this hierarchal structure is removed and you can more easily parse the individual address components independent of their relationship to one another.

(response truncated)
{
  ...
  "address_components" : [
    {
      "long_name" : "1600",
      "short_name" : "1600",
      "types" : [ "street_number" ]
    },
    {
      "long_name" : "Amphitheatre Parkway",
      "short_name" : "Amphitheatre Pkwy",
      "types" : [ "route" ]
    },
    {
      "long_name" : "Mountain View",
      "short_name" : "Mountain View",
      "types" : [ "locality", "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" ]
    }
  ],
  ...
}

Code that uses the v3 API no longer has to assume that the street is immediately contained by a locality, which is contained by a state.

Robust geocode response

With the new flatter structure comes a robust geocode response which gives you more control over how you interact and utilize the returned data. A few noteworthy examples include:

  • A long_name and short_name field are now returned for each address component. This is useful if, for example, you wanted to fetch the full state name (California) instead of its abbreviation (CA), or vice-versa.
  • location_type now gives you more information regarding the level of precision for the resulting geocode (e.g., rooftop, interpolated, geometric center approximate accuracy). This is a change from the Accuracy field in v2, which contained the granularity of the feature returned (e.g., street address, road, city, locality, etc). With location_type you will now have the precision of the geocode returned in addition to the type of feature that was returned.
  • partial_match stores information on whether the returned geocode exactly or partially matches your original query. You can use this field in conjunction with location_type to fetch more information on the accuracy of the geocode result.
  • types[] is an array indicating the address types of each address component. An address component may have multiple address types (e.g., a city can be flagged as locality as well as a political entity). The service returns an array of address types associated with a given address, giving you more flexibility as to how the response is parsed.

Please see our documentation for a complete discussion on the new response format.

Strict filtering via the components filter.

Now you can limit geocode results by route, country, locality, postal code, and administrative areas such as counties. This is useful if you wanted to return only those localities named “Paris” in the United States and not the more prominent “Paris, France”.

Where to go from here

You can get started by reviewing the Geocoding API documentation.

Maps API for Business customers, once familiarized with the v3 Geocoding API documentation, should closely review the Maps API for Business specific documentation for information on URL formatting and URL signing.

And, lastly, please take the time to review the default Maps API for Business usage limits for the supported web services.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.