Using the Geocoder API

Geocoding

To geocode an address, simply create a geocoder instance, and request a geocode.

>>> g = Geocoder()
>>> results = g.geocode('1600 Amphitheatre Pkwy')

If you want to provide any additional parameters that the Maps API accepts, send them after the address.

>>> g.geocode('Toledo', region='es', language='es', sensor='true')

See working_with_results for what to do next.

Reverse Geocoding

To do a reverse geocode, simply use the reverse_geocode method and provide lat/lng values

>>> g = Geocoder()
>>> results = g.reverse_geocode(37.4220827, -122.08289)

See working_with_results for what to do next.

Working with Results

If the geocode is successful, you will have an object that is has a list of geocoded results. You can check the number of results returned.

>>> len(results)
1

You can access each result by referencing its index in your result set.

>>> first_result = results[0]

Once you have geocoded an address, it is very easy to work with. There are a couple convenience methods for the GeoResult object.

The string representation will always be the formatted address. You can also access formatted address directly, coordinates, and a boolean check is_valid_address to see if the address is a valid street address. Finally, there is a raw attribute which gives you access to the raw data returned by the Google Maps API.

>>> str(first_result)
'1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA'

>>> first_result.formatted_address
u'1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA'

>>> first_result.coordinates
(37.4220827, -122.08289)

>>> first_result.is_valid_address
True

The ‘address_components’ that the Maps API provides are made easily accessible by simple attribute lookups.

>>> first_result.street_number
u'1600'
>>> first_result.postal_code
u'94043'
>>> first_result.country
u'United States'

By default, the GeoResult will give you the ‘long_name’ of the address component. If you want the short name, just add it to your attribute lookup.

>>> first_result.country__short_name
u'US'