10.1. Introduction to ggeocoder

gggeocoder is a python module that makes it easy for developers to locate the coordinates of addresses, cities, countries, and landmarks across the globe using third-party geocoders and other data sources, such as wikis.


ggeocoder is just one example of a geocoding module. There are
many geocoders out there (even in Python) that call various services, including google. There are also DB vendors that sell static geocoding DBs, or provide them for free.

The ggeocoder modules currently includes support for For more info on general capabilities, see http://code.google.com/p/geopy/wiki/GettingStarted.

Here is a brief demo of how it might be used:

from ggeocoder import Geocoder
g = Geocoder()
place_str = '20 Clay, Irvine, CA'
response = g.geocode(place_str,exactly_one=False)
places = [(r.formatted_address,r.coordinates)  for r in response.data]

Such pairs can then be fed to a variety of applications. A natural idea is to create kml files and call Google earth. The following code snippet works on a Mac:

import subprocess
kml_file = 'google.kml'
coordinates = [coords for (address, coords) in places]
createKML(coordinates, place_str, kml_file)
cmd_str = 'open /Applications/Google\ Earth.app %s' % kml_file
subprocess.call(cmd_str, shell=True)

Here createKML is a function that creates a KML file in the given location, given a place string and coordinates. This is the appropriate XML-type file to pass to Google Earth. The entire script, including createKML, can be found here.

The kml file created looks like this:

<?xml version="1.0" ?>
   <description>20 Clay, Irvine, CA 92620, USA</description>

Note that there is added information. This is because Google returns a complete description string for each location and that description often contains additional informatoion not in t he original request string, in this case, the zip code.

As of this writing, Google’s Geocoding services were rate-limited under the following policy:

"Use of the Google Geocoding API is subject to a query limit of 2,500 geolocation requests per day."

Google will return errors to requests that exceed its API policies. Among the errors to watch for is Error Code 620, “Too fast for Google to follow.” This means geocoding requests are not being properly spaced out. Persisting in making ill-timed requests will lead to the service being cut off, possibly permanently.

There are other geocoding services besides Google’s, though they don’t all work on the same pages. Here are a few examples:

  1. Yahoo Maps
  2. Mapquest. Visit here for API Key.
  3. Windows Local Live (Virtual Earth)
  4. geocoder.us
  5. GeoNames
  6. MediaWiki pages (with the GIS extension) This is just a large repository of pages with the .GIS extensions that have coordinate information.
  7. Semantic MediaWiki An extension of MediaWiki.