Upgrading Your Geocoding API Application To v3

Samuel Baroman, Google Enterprise Support TeamFebruary 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.

What’s new in Version 3 of the Geocoding API

New endpoint

The v3 Geocoder uses a different URL endpoint:

https://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.

In addition to the above parameters, Google Maps API for Work customers are required to supply a client ID
parameter and a digital signature to use the Geocoding API. The
client ID links your Google Maps API for Work 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:

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

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