Clone wiki

pygeocoder / Home

pygeocoder 1.2.5

pygeocoder is a Python library that helps you make use of Google's Geocoding functionality. With this module, you can easily find addresses corresponding to coordinates and vice versa. You can also use it to validate and format addresses.

It is based on googlemaps 1.0.2 but upgraded to make use of Google's newest geocoding API V3




To install, you can simply use:

$ pip install pygeocoder

pip is a newer generation replacement for easy_install. Support Python advancement for a better package distribution system and make the switch today.


New in pygeocoder 1.1.3: it is no longer necessary to instantiate a Geocoder class. Geocoder methods are static methods but still support instance calls.

Note in pygeocoder 1.2: address_to_latlng and latlng_to_address were removed. They were 'shortcuts' that were long to type and feature incomplete. Just use Geocoder.geocode('some address').coordinates instead.


from pygeocoder import Geocoder
results = Geocoder.geocode("Tian'anmen, Beijing")
>>> (39.908715, 116.397389)
>>> Tiananmen, Dongcheng, Beijing, China, 100051

For the first result, you don't have to specify the index.

>>> 1
>>> Tiananmen, Dongcheng, Beijing, China, 100051

Besides the coordinates, returns of the geocode method also returns all location component types used by Google API. For instance:

>>> 'China'
>>> '100051'

Instead of using results with indices, you can also use iterators

results = Geocoder.geocode("McGill University")
for result in results:

>>> H3A
>>> H2X 2C3
>>> G1V
>>> H2X 2C3

You can also access the dictionary of results directly using


The contents are described in the Google documentation for Geocoding

Reverse Geocoding

results = Geocoder.reverse_geocode(45.424571, -75.695661)
>>> 1 Wellington St, Ottawa, ON K1A 0A6, Canada

Descriptions of the raw dictionary content from reverse geocoding are found here

Address Validation and Formatting

This module can be used to validate and format user inputted addresses.

Geocoder.geocode("1600 amphitheater parkway, mountain view").valid_address
>>> True
Geocoder.geocode("1600000 amphicinema parkway, mountain view").valid_address
>>> False

It can also correct minor spelling mistakes and give back a properly formatted address

result = Geocoder.geocode("1600 amphiteather parkway, mountain view")
>>> True
>>> 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA

Then, you can use the properly split address components to store separately in database as used above

>>> 1600
>>> 'Amphitheater Pkwy'

Maps API for Business Users

Use an initialised instance of Geocoder like this

business_geocoder = Geocoder(client_id='MY_CLIENT_ID', private_key='MY_PRIVATE_KEY')
business_geocoder.geocode('blah') #business as usual

To use your cryptographic key

Despite documentation, Simple API keys are also still supported. To continue using your Simple API keys, do

business_geocoder = Geocoder(api_key='MY_SIMPLE_API_KEY')
business_geocoder.geocode('blah') #business as usual

HTTP Proxy

To use HTTP proxy servers, you must instantiate Geocoder and call set_proxy(proxy) on the instance. Proxy can be of form ''.

You're responsible to catch requests.exceptions.ConnectionError if the proxy server has issues.