"""Retrieve a JSON object from a (parameterized) URL.

:param query_url: The base URL to query

:type query_url: string

:param params: Dictionary mapping (string) query parameters to values

:type params: dict

:param headers: Dictionary giving (string) HTTP headers and values

:type headers: dict

:return: A `(url, json_obj)` tuple, where `url` is the final,

parameterized, encoded URL fetched, and `json_obj` is the data

fetched from that URL as a JSON-format object.

:rtype: (string, dict or array)

"""

encoded_params = urllib.urlencode(params)

url = query_url + encoded_params

request = urllib2.Request(url, headers=headers)

response = urllib2.urlopen(request)

"""Base class for errors in the :mod:`googlemaps` module.

Methods of the :class:`GoogleMaps` raise this when something goes wrong.

"""

#: See http://code.google.com/apis/maps/documentation/geocoding/index.html#StatusCodes

#: for information on the meaning of these status codes.

G_GEO_SUCCESS = 200

G_GEO_SERVER_ERROR = 500

G_GEO_MISSING_QUERY = 601

G_GEO_UNKNOWN_ADDRESS = 602

G_GEO_UNAVAILABLE_ADDRESS = 603

G_GEO_BAD_KEY = 610

G_GEO_TOO_MANY_QUERIES = 620

_STATUS_MESSAGES = {

G_GEO_SUCCESS : 'G_GEO_SUCCESS',

G_GEO_SERVER_ERROR : 'G_GEO_SERVER_ERROR',

G_GEO_MISSING_QUERY : 'G_GEO_MISSING_QUERY',

G_GEO_UNKNOWN_ADDRESS : 'G_GEO_UNKNOWN_ADDRESS',

G_GEO_UNAVAILABLE_ADDRESS : 'G_GEO_UNAVAILABLE_ADDRESS',

G_GEO_BAD_KEY : 'G_GEO_BAD_KEY',

G_GEO_TOO_MANY_QUERIES : 'G_GEO_TOO_MANY_QUERIES',

}

def __init__(self, status, url=None, response=None):

"""Create an exception with a status and optional full response.

:param status: Either a ``G_GEO_`` code or a string explaining the

exception.

:type status: int or string

:param url: The query URL that resulted in the error, if any.

:type url: string

:param response: The actual response returned from Google, if any.

:type response: dict

"""

Exception.__init__(self, status) # Exception is an old-school class

self.status = status

self.response = response

self.url = url

def __str__(self):

"""Return a string representation of this :exc:`GoogleMapsError`."""

if self.status in self._STATUS_MESSAGES:

if self.response is not None and 'responseDetails' in self.response:

retval = 'Error %d: %s' % (self.status, self.response['responseDetails'])

else:

retval = 'Error %d: %s' % (self.status, self._STATUS_MESSAGES[self.status])

else:

retval = str(self.status)

return retval

def __unicode__(self):

"""Return a unicode representation of this :exc:`GoogleMapsError`."""

"""

An easy-to-use Python wrapper for the Google Maps and Local Search APIs.

**Geocoding**: convert a postal address to latitude and longitude

>>> from googlemaps import GoogleMaps

>>> gmaps = GoogleMaps(api_key)

>>> address = 'Constitution Ave NW & 10th St NW, Washington, DC'

>>> lat, lng = gmaps.address_to_latlng(address)

>>> print lat, lng

38.8921021 -77.0260358

**Reverse Geocoding**: find the nearest address to (lat, lng)

>>> destination = gmaps.latlng_to_address(38.887563, -77.019929)

>>> print destination

Independence and 6th SW, Washington, DC 20024, USA

**Local Search**: find places matching a query near a given location

>>> local = gmaps.local_search('cafe near ' + destination)

>>> print local['responseData']['results'][0]['titleNoFormatting']

Vie De France Bakery & Cafe

**Directions**: turn-by-turn directions, distance, time, etc. from

point A to point B

>>> directions = gmaps.directions(address, destination)

>>> print directions['Directions']['Distance']['meters']

1029

>>> print directions['Directions']['Duration']['seconds']

106

>>> for step in directions['Directions']['Routes'][0]['Steps']:

... print step['descriptionHtml']

Head <b>east</b> on <b>Constitution Ave NW</b> toward <b>9th St NW</b>

Take the 2nd <b>right</b> onto <b>7th St NW</b>

Turn <b>left</b> at <b>Independence Ave SW</b>

This software is in no way associated with or endorsed by Google Inc.

Use of the Google Maps API is governed by its Terms of Service:

http://code.google.com/apis/maps/terms.html. Note in particular that

you will need your own Google Maps API key to use this service,

and that there are rate limits to the number of requests you can

make.

"""

_GEOCODE_QUERY_URL = 'http://maps.google.com/maps/geo?'

_DIRECTIONS_QUERY_URL = 'http://maps.google.com/maps/nav?'

_LOCAL_QUERY_URL = 'http://ajax.googleapis.com/ajax/services/search/local?'

_LOCAL_RESULTS_PER_PAGE = 8

MAX_LOCAL_RESULTS = 32

def __init__(self, api_key='', referrer_url=''):

"""

Create a new :class:`GoogleMaps` object using the given `api_key` and

`referrer_url`.

:param api_key: Google Maps API key

:type api_key: string

:param referrer_url: URL of the website using or displaying information

from this module.

:type referrer_url: string

Google requires API users to register for an API key before using the

geocoding service; this can be done at

http://code.google.com/apis/maps/signup.html.

If you are not geocoding, you do not need an API key.

Use of Google Local Search requires a referrer URL, generally the website

where the retrieved information will be used. If you are not using

Local Search, you do not need a referrer URL.

"""

self.api_key = api_key

self.referrer_url = referrer_url

def geocode(self, query, sensor='false', oe='utf8', ll='', spn='', gl=''): # pylint: disable-msg=C0103,R0913

"""

Given a string address `query`, return a dictionary of information about

that location, including its latitude and longitude.

Interesting bits:

>>> gmaps = GoogleMaps(api_key)

>>> address = '350 Fifth Avenue New York, NY'

>>> result = gmaps.geocode(address)

>>> placemark = result['Placemark'][0]

>>> lng, lat = placemark['Point']['coordinates'][0:2] # Note these are backwards from usual

>>> print lat, lng

40.6721118 -73.9838823

>>> details = placemark['AddressDetails']['Country']['AdministrativeArea']

>>> street = details['Locality']['Thoroughfare']['ThoroughfareName']

>>> city = details['Locality']['LocalityName']

>>> state = details['AdministrativeAreaName']

>>> zipcode = details['Locality']['PostalCode']['PostalCodeNumber']

>>> print ', '.join((street, city, state, zipcode))

350 5th Ave, Brooklyn, NY, 11215

More documentation on the format of the return value can be found at

Google's `geocoder return value`_ reference. (Note: Some places have

a `'SubAdministrativeArea'` and some don't; sometimes a `'Locality'`

will have a `'DependentLocality'` and some don't.)

.. _`geocoder return value`: http://code.google.com/apis/maps/documentation/geocoding/index.html#JSON

:param query: Address of location to be geocoded.

:type query: string

:param sensor: ``'true'`` if the address is coming from, say, a GPS device.

:type sensor: string

:param oe: Output Encoding; best left at ``'utf8'``.

:type oe: string

:param ll: `lat,lng` of the viewport center as comma-separated string;

must be used with `spn` for Viewport Biasing

:type ll: string

:param spn: The "span" of the viewport; must be used with `ll`.

:type spn: string

:param gl: Two-character ccTLD_ for country code biasing.

:type gl: string

:returns: `geocoder return value`_ dictionary

:rtype: dict

:raises GoogleMapsError: if there is something wrong with the query.

More information on the types and meaning of the parameters can be found

at the `Google HTTP Geocoder`__ site.

__ http://code.google.com/apis/maps/documentation/geocoding/index.html

.. _ccTLD: http://en.wikipedia.org/wiki/Country_code_top-level_domain

"""

if (ll is None and spn is not None) or (ll is not None and spn is None):

raise GoogleMapsError('Both ll and spn must be provided.')

params = {

'q': query,

'key': self.api_key,

'sensor': sensor,

'output': 'json',

'oe': oe,

'll': ll,

'spn': spn,

'gl': gl,

}

url, response = fetch_json(self._GEOCODE_QUERY_URL, params=params)

status_code = response['Status']['code']

if status_code != STATUS_OK:

raise GoogleMapsError(status_code, url, response)

return response

def reverse_geocode(self, lat, lng, sensor='false', oe='utf8', ll='', spn='', gl=''): # pylint: disable-msg=C0103,R0913

"""

Converts a (latitude, longitude) pair to an address.

Interesting bits:

>>> gmaps = GoogleMaps(api_key)

>>> reverse = gmaps.reverse_geocode(38.887563, -77.019929)

>>> address = reverse['Placemark'][0]['address']

>>> print address

Independence and 6th SW, Washington, DC 20024, USA

>>> accuracy = reverse['Placemark'][0]['AddressDetails']['Accuracy']

>>> print accuracy

9

:param lat: latitude

:type lat: float

:param lng: longitude

:type lng: float

:return: `Reverse geocoder return value`_ dictionary giving closest

address(es) to `(lat, lng)`

:rtype: dict

:raises GoogleMapsError: If the coordinates could not be reverse geocoded.

Keyword arguments and return value are identical to those of :meth:`geocode()`.

.. _`Reverse geocoder return value`:

http://code.google.com/apis/maps/documentation/geocoding/index.html#ReverseGeocoding

"""

return self.geocode("%f,%f" % (lat, lng), sensor=sensor, oe=oe, ll=ll, spn=spn, gl=gl)

def address_to_latlng(self, address):

"""

Given a string `address`, return a `(latitude, longitude)` pair.

This is a simplified wrapper for :meth:`geocode()`.

:param address: The postal address to geocode.

:type address: string

:return: `(latitude, longitude)` of `address`.

:rtype: (float, float)

:raises GoogleMapsError: If the address could not be geocoded.

"""

return tuple(self.geocode(address)['Placemark'][0]['Point']['coordinates'][1::-1])

def latlng_to_address(self, lat, lng):

"""

Given a latitude `lat` and longitude `lng`, return the closest address.

This is a simplified wrapper for :meth:`reverse_geocode()`.

:param lat: latitude

:type lat: float

:param lng: longitude

:type lng: float

:return: Closest postal address to `(lat, lng)`, if any.

:rtype: string

:raises GoogleMapsError: if the coordinates could not be converted

to an address.

"""

return self.reverse_geocode(lat, lng)['Placemark'][0]['address']

def local_search(self, query, numresults=_LOCAL_RESULTS_PER_PAGE, **kwargs):

"""

Searches Google Local for the string `query` and returns a

dictionary of the results.

>>> gmaps = GoogleMaps(api_key)

>>> local = gmaps.local_search('sushi san francisco, ca')

>>> result = local['responseData']['results'][0]

>>> print result['titleNoFormatting']

Sushi Groove

>>> print result['streetAddress']

1916 Hyde St

>>> print result['phoneNumbers'][0]['number']

(415) 440-1905

For more information on the available data, see Google's documentation on

`AJAX result structure`_ and `local result properties`_.

The return value of this method is slightly different than that

documented by Google; it attempts to stuff as many results as

possible, from several queries (up to `numresults`), into the

``['responseData']['results']`` array. As a result, fields of

the results referencing this array (such as ``'cursor'``,

``'currentPageIndex'``, ``'moreResultsUrl'``) may not make

complete sense.

This method may return fewer results than you ask for; Google Local

returns a maximum of :data:`GoogleMaps.MAX_LOCAL_RESULTS` results.

:param query: String containing a search and a location, such as

``'Sushi San Francisco, CA'``.

:type query: string

:param numresults: Number of results to return, up to a maximum of :data:`MAX_LOCAL_RESULTS`.

:type numresults: int

:param kwargs: You can pass additional `AJAX search arguments`_ and they

will be tacked on to the query.

:return: A Google `AJAX result structure`_.

:rtype: dict

:raises GoogleMapsError: If the query was malformed.

.. _AJAX result structure: http://code.google.com/apis/ajaxsearch/documentation/#fonje

.. _local result properties: http://code.google.com/apis/ajaxsearch/documentation/reference.html#_class_GlocalResult

.. _AJAX search arguments: http://code.google.com/apis/ajaxsearch/documentation/reference.html#_intro_fonje

"""

params = {

'q': query,

'v': '1.0',

'rsz': 'large', # Return 8 results per page instead of 4

#'key': self.api_key, # Google Local seems not to like empty keys

}

params.update(kwargs)

start = 0

results = None

while start < numresults and start < self.MAX_LOCAL_RESULTS:

params['start'] = start

url, response = fetch_json(self._LOCAL_QUERY_URL, params=params, headers={'Referer': self.referrer_url})

status_code = response['responseStatus']

if status_code != STATUS_OK:

raise GoogleMapsError(status_code, url=url, response=response)

if results is None:

results = response

else:

results['responseData']['results'].extend(response['responseData']['results'])

# If we didn't get a full page of results, Google has run out; don't try again

if len(response['responseData']['results']) < self._LOCAL_RESULTS_PER_PAGE:

break

start += len(response['responseData']['results'])

if results is not None:

results['responseData']['results'] = results['responseData']['results'][:numresults]

return results

def directions(self, origin, destination, **kwargs):

"""

Get driving directions from `origin` to `destination`.

Interesting bits:

>>> gmaps = GoogleMaps(api_key)

>>> start = 'Constitution Ave NW & 10th St NW, Washington, DC'

>>> end = 'Independence and 6th SW, Washington, DC 20024, USA'

>>> dirs = gmaps.directions(start, end)

>>> time = dirs['Directions']['Duration']['seconds']

>>> dist = dirs['Directions']['Distance']['meters']

>>> route = dirs['Directions']['Routes'][0]

>>> for step in route['Steps']:

... print step['Point']['coordinates'][1], step['Point']['coordinates'][0]

... print step['descriptionHtml']

38.8921 -77.02604

Head <b>east</b> on <b>Constitution Ave NW</b> toward <b>9th St NW</b>

38.89208 -77.02191

Take the 2nd <b>right</b> onto <b>7th St NW</b>

38.88757 -77.02191

Turn <b>left</b> at <b>Independence Ave SW</b>

:param origin: Starting address

:type origin: string

:param destination: Ending address

:type destination: string

:param kwargs: You can pass additional URL parameters as keyword arguments,

but this functionality is not documented.

:return: Dictionary containing driving directions.

:rtype: dict

:raises GoogleMapsError: If Google Maps was unable to find directions.

"""

params = {

'q': 'from:%s to:%s' % (origin, destination),

'output': 'json',

'oe': 'utf8',

'key': self.api_key,

}

params.update(kwargs)

url, response = fetch_json(self._DIRECTIONS_QUERY_URL, params=params)

status_code = response['Status']['code']

if status_code != STATUS_OK:

raise GoogleMapsError(status_code, url=url, response=response)

"""

Geocodes a location given on the command line.

Usage:

googlemaps.py "1600 amphitheatre mountain view ca" [YOUR_API_KEY]

googlemaps.py 37.4219720,-122.0841430 [YOUR_API_KEY]

When providing a latitude and longitude on the command line, ensure

they are separated by a comma and no space.

"""

if len(argv) < 2 or len(argv) > 4:

print main.__doc__

sys.exit(1)

query = argv[1]

if len(argv) == 3:

api_key = argv[2]

else:

api_key = raw_input("Google Maps API key: ")

gmap = GoogleMaps(api_key)

try:

result = gmap.geocode(query)

except GoogleMapsError, err:

sys.stderr.write('%s\n%s\nResponse:\n' % (err.url, err))

json.dump(err.response, sys.stderr, indent=4)

sys.exit(1)

json.dump(result, sys.stdout, indent=4)

"""Does BFS on JSON-like object `obj` to find a dict with a key == to `key` and

returns the associated value. Returns None if it didn't find `key`."""

queue = [obj]

while queue:

item = queue.pop(0)

if type(item) is list:

queue.extend(item)

elif type(item) is dict:

for k in item:

if k == key:

return item[k]

else:

queue.append(item[k])

"""Unit tests for googlemaps."""

def test_geocode(self):

"""Test googlemaps geocode() and address_to_latlng()"""

addr = '1600 amphitheatre mountain view ca'

gmaps = GoogleMaps(GMAPS_API_KEY)

result = gmaps.geocode(addr)

self.assertEqual(result['Status']['code'], 200)

self.assertEqual(searchkey(result, 'CountryName'), 'USA')

self.assertEqual(searchkey(result, 'PostalCodeNumber'), '94043')

self.assertEqual(searchkey(result, 'ThoroughfareName'), '1600 Amphitheatre Pkwy')

self.assertEqual(searchkey(result, 'LocalityName'), 'Mountain View')

self.assertEqual(searchkey(result, 'AdministrativeAreaName'), 'CA')

self.assertEqual(searchkey(result, 'CountryNameCode'), 'US')

self.assertEqual(searchkey(result, 'address'), '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA')

lat, lng = searchkey(result, 'coordinates')[1::-1]

self.assertAlmostEquals(lat, 37.422125, 3)

self.assertAlmostEquals(lng, -122.084466, 3)

(lat2, lng2) = gmaps.address_to_latlng(addr)

self.assertAlmostEqual(lat, lat2, 3)

self.assertAlmostEqual(lng2, lng2, 3)

def test_reverse_geocode(self):

"""Test googlemaps reverse_geocode() and latlng_to_address()"""

lat, lng = 40.714224, -73.961452

gmaps = GoogleMaps(GMAPS_API_KEY)

result = gmaps.reverse_geocode(lat, lng)

self.assertEqual(result['Status']['code'], 200)

result = result['Placemark'][0]

self.assertEqual(searchkey(result, 'CountryName'), 'USA')

self.assertEqual(searchkey(result, 'PostalCodeNumber'), '11211')

self.assertEqual(searchkey(result, 'ThoroughfareName'), '277 Bedford Ave')

self.assertEqual(searchkey(result, 'LocalityName'), 'Brooklyn')

self.assertEqual(searchkey(result, 'AdministrativeAreaName'), 'NY')

self.assertEqual(searchkey(result, 'CountryNameCode'), 'US')

addr = searchkey(result, 'address')

self.assertEqual(addr, '277 Bedford Ave, Brooklyn, NY 11211, USA')

lat2, lng2 = searchkey(result, 'coordinates')[1::-1]

self.assertAlmostEquals(lat, lat2, 3)

self.assertAlmostEquals(lng, lng2, 3)

addr2 = gmaps.latlng_to_address(lat, lng)

self.assertEqual(addr, addr2)

def test_local_search(self):

"""Test googlemaps local_search()."""

gmaps = GoogleMaps(GMAPS_API_KEY, referrer_url='http://www.google.com/')

local = gmaps.local_search('sushi san francisco, ca')

result = local['responseData']['results'][0]

self.assertEqual(result['titleNoFormatting'], 'Sushi Groove')

results = gmaps.local_search('Starbucks Los Angeles, CA', numresults=GoogleMaps.MAX_LOCAL_RESULTS)

self.assertEqual(results['responseStatus'], googlemaps.STATUS_OK)

self.assertNotEqual(results['responseData'], None)

self.assertNotEqual(results['responseData']['cursor'], None)

results = results['responseData']['results']

self.assertEqual(len(results), GoogleMaps.MAX_LOCAL_RESULTS)

for result in results:

self.assertEqual(result['GsearchResultClass'], 'GlocalSearch')

self.assert_(result['titleNoFormatting'].lower().find('starbucks') >= 0)

self.assertEqual(result['region'], 'CA')

def test_directions(self):

"""Test googlemaps directions()"""

gmaps = GoogleMaps(GMAPS_API_KEY)

results = gmaps.directions('Constitution Ave NW & 10th St NW, Washington, DC',

'Independence and 6th SW, Washington, DC 20024, USA')

self.assertEqual(results['Status']['code'], googlemaps.STATUS_OK)

self.assert_(results['Directions']['Duration']['seconds'] in range(100, 130))

self.assert_(results['Directions']['Distance']['meters'] in range(1000, 1050))

routes = results['Directions']['Routes']

self.assert_(len(routes) >= 1)

self.assertEqual(routes[0]['Duration'], results['Directions']['Duration'])

self.assertEqual(routes[0]['Distance'], results['Directions']['Distance'])

self.assert_(routes[0]['Steps'][0]['descriptionHtml'].find('Constitution Ave') >= 0)

self.assert_(routes[0]['Steps'][1]['descriptionHtml'].find('7th St') >= 0)

self.assert_(routes[0]['Steps'][2]['descriptionHtml'].find('Independence Ave') >= 0)

def test_doctests(self):

"""Run googlemaps doctests"""