geopy

geopy is a geocoding toolbox for Python.

Description

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

Development Status

Under development since September 2006. Latest release: 0.93.

License

geopy is open source software released under the MIT license.

Contact

Questions, comments, and bug reports are welcome at exogen@gmail.com, the geopy mailing list, and on brian's blog.

Install

From the Cheese Shop:

$ sudo easy_install geopy

From the Subversion repository:

$ svn co http://geopy.googlecode.com/svn/trunk/ geopy-trunk
$ cd geopy-trunk/
$ sudo python setup.py install

...or use easy_install:

$ sudo easy_install http://geopy.googlecode.com/svn/trunk/

Geocoders

geopy includes geocoder classes for MediaWiki (with the GIS extension), Semantic MediaWiki, the Google geocoder, the Yahoo! geocoder, geocoder.us, Virtual Earth, and GeoNames.

The geocoder classes are located in geopy.geocoders. >>> from geopy import geocoders

Using the Google geocoder (get an API Key):

>>> g = geocoders.Google('YOUR_API_KEY_HERE') >>> place, (lat, lng) = g.geocode("10900 Euclid Ave in Cleveland") >>> print "%s: %.5f, %.5f" % (place, lat, lng) 10900 Euclid Ave, Cleveland, OH 44106, USA: 41.50489, -81.61027

You can use the Google geocoder without an API key by querying the actual Google Maps interface instead. This geocoder is supposedly more up-to-date and thus may have more addresses available:

>>> g = geocoders.Google(resource='maps', output_format='js')

To geocode addresses in other countries with the Google geocoder, specify an alternate domain to query. For example, this currently seems to produce the best results for UK addresses:

>>> g = geocoders.Google(domain='maps.google.co.uk', resource='maps', output_format='js')

Using the Yahoo! geocoder (get an Application ID):

>>> y = geocoders.Yahoo('YOUR_APP_ID_HERE') >>> place, (lat, lng) = y.geocode("Thames Street, Newport, RI") >>> print "%s: %.5f, %.5f" % (place, lat, lng) [241-251] THAMES ST, NEWPORT, RI 02840, US: 41.48696, -71.31490

Using the Virtual Earth geocoder:

>>> ve = geocoders.VirtualEarth() >>> place, (lat, lng) = ve.geocode("Microsoft HQ in Redmond, WA") >>> print "%s: %.5f, %.5f" % (place, lat, lng) Microsoft (business center), Redmond, Washington, United States: 47.64058, -122.12906

Using the geocoder.us geocoder (free for non-commercial purposes, otherwise get an account):

>>> us = geocoders.GeocoderDotUS() >>> place, (lat, lng) = us.geocode("1600 Pennsylvania Ave, Washington DC") >>> print "%s: %.5f, %.5f" % (place, lat, lng) 1600 Pennsylvania Ave NW, Washington, DC 20502: 38.89875, -77.03768

Using the GeoNames geocoder:

>>> gn = geocoders.GeoNames() >>> place, (lat, lng) = gn.geocode("Cleveland, OH 44106") >>> print "%s: %.5f, %.5f" % (place, lat, lng) Cleveland, US 44106: 41.50475, -81.60280

GeoNames only returns city, country and zip code in its "canonical" name, so it looks a little funny.

Using the MediaWiki geocoder:

>>> wiki = geocoders.MediaWiki("http://wiki.case.edu/%s") >>> place, (lat, lng) = wiki.geocode('Wade Commons') >>> print "%s: %.5f, %.5f" % (place, lat, lng) Wade_Commons: 41.51304, -81.60525

Using the Semantic MediaWiki geocoder:

>>> wiki = geocoders.SemanticMediaWiki("http://wiki.case.edu/%s", ... attributes=['Coordinates'], ... relations=['Located in']) >>> place, (lat, lng) = wiki.geocode("Project Club") >>> print "%s: %.5f, %.5f" % (place, lat, lng) Olin Building: 41.50224, -81.60778

Every geocoder accepts an argument format_string that defaults to '%s' where the input string to geocode is interpolated. For example, if you only need to geocode locations in Cleveland, Ohio, you could do:

>>> us = geocoders.GeocoderDotUs(format_string="%s, Cleveland OH") >>> place (lat, lng) = us.geocode("11111 Euclid Ave") >>> print "%s: %.5f, %.5f" % (place, lat, lng) 11111 Euclid Ave, Cleveland, OH 44106: 41.50678, -81.60815

Geocoders that can return multiple possible locations for a query accept an argument exactly_one to their geocode method which defaults to True. A ValueError will be raised if 0 or more than 1 locations are returned. If exactly_one is False, geocode will return a generator of the retured locations:

>>> for place, (lat, lng) in g.geocode('1296 Magnolia Dr in Cleveland', ... exactly_one=False): ... print "%s: %.5f, %.5f" % (place, lat, lng) 1670 Magnolia Dr, Cleveland, OH 44106, USA: 41.51211, -81.60704 199 Magnolia Dr, Cleveland, OH 44110, USA: 41.58104, -81.56251 >>> list(g.geocode('1296 Magnolia Dr in Cleveland', exactly_one=False)) [(u'1670 Magnolia Dr, Cleveland, OH 44106, USA', (41.512107999999998, -81.607044999999999)), (u'199 Magnolia Dr, Cleveland, OH 44110, USA', (41.581035999999997, -81.562505000000002))]

For advanced usage, see help(geocoders), the docstrings for each class are fairly complete.

You can also view the syntax-highlighted source code for geopy.geocoders.

Parsing Utilities

If you just need to parse geographical coordinates, the util.parse_geo method makes this easy:

>>> from geopy import util >>> util.parse_geo("39.3° N 76.6° W") (39.299999999999997, -76.599999999999994) >>> util.parse_geo("41.12345;-81.98765") (41.123449999999998, -81.987650000000002) >>> util.parse_geo(u"23° 26′ 22″ N 23° 27′ 30″ E") (23.439444444444444, 23.458333333333332)

Distance Calculation

In version 0.93, support was added for geodesic distance calculation. Two distance formulas are included: great-circle distance and Vincenty distance.

Great-circle distance uses a spherical model of the earth, using the average great-circle radius of 6372.795 kilometers, resulting in an error of up to about 0.5%. The radius value is stored in distance.EARTH_RADIUS, so it can be customized (it should always be in kilometers, however).

Vincenty distance uses a more accurate ellipsoidal model of the earth. This is the default distance formula, and is thus aliased as distance.distance — so you can easily swap out distance formulas just by changing distance.distance at the top of your code. There are multiple popular ellipsoidal models, and which one will be the most accurate depends on where your points are located on the earth. The default is the WGS-84 ellipsoid, which is the most globally accurate. geopy includes a few other models in the distance.ELLIPSOIDS dictionary:

# model major (km) minor (km) flattening ELLIPSOIDS = {'WGS-84': (6378.137, 6356.7523142, 1 / 298.257223563), 'GRS-80': (6378.137, 6356.7523141, 1 / 298.257222101), 'Airy (1830)': (6377.563396, 6356.256909, 1 / 299.3249646), 'Intl 1924': (6378.388, 6356.911946, 1 / 297.0), 'Clarke (1880)': (6378.249145, 6356.51486955, 1 / 293.465), 'GRS-67': (6378.1600, 6356.774719, 1 / 298.25), }

Here's an example usage of distance.distance:

>>> from geopy import distance >>> _, ne = g.geocode('Newport, RI') >>> _, cl = g.geocode('Cleveland, OH') >>> distance.distance(ne, cl).miles 538.37173614757057

Using Great-circle distance:

>>> distance.distance = distance.GreatCircleDistance >>> distance.distance(ne, cl).miles 537.12986466281222

You can change the ellipsoid model used by the Vincenty formula like so:

>>> distance.VincentyDistance.ELLIPSOID = 'Intl 1924'

The above model name will automatically be retrieved from the ELLIPSOIDS dictionary. Alternatively, you can specify the model values directly:

>>> distance.VincentyDistance.ELLIPSOID = (6377., 6356., 1 / 297.)

Distances support simple arithmetic, making it easy to do things like calculate the length of a path:

>>> d = distance.distance >>> _, wa = g.geocode('Washington, DC') >>> _, pa = g.geocode('Palo Alto, CA') >>> (d(ne, cl) + d(cl, wa) + d(wa, pa)).miles 3276.157156868931

The distance module also contains useful routines for converting between length and angle units. Read the syntax-highlighted source code or use help(distance) for more documentation.

Thanks for reading. This page is supported by AdSense.