tethne.services.geocode module

This module provides classes for geocoding bibliographic data.

Each geocoder class should be based on BaseCoder, and provide code and get_location methods that can be used by BaseCoder.code_this() and BaseCoder.code_list().

BaseCoder should not be used directly. Instead, instantiate a child class, e.g. GoogleCoder. For example:

>>> from tethne.services.geocode import GoogleCoder
>>> google = GoogleCoder()
>>> location = google.code_this("Marine Biological Laboratory")
>>> location
<tethne.services.geocode.Location object at 0x10153af10>

>>> location.__dict__
{'latitude': 41.5250098, 'place': u'Marine Biological Laboratory, 7 M B L Street, Woods Hole, MA 02543, USA', 'longitude': -70.6712845}

To avoid making redundant and costly requests, BaseCoder implements a rather crude cacheing system, using Pickle. Previous results are held in memory until the BaseCoder is destroyed, at which time the placename-Location mapping is pickled in the current working directory as .geocache.pickle. Disable by setting persistent to False.

sleep_interval determines the wait (in seconds) between API calls, to avoid triggering rate-limiting.

Location([place, latitude, longitude])	Minimal geographic datum yielded by geocoders.
BaseCoder(**kwargs)	Base class for geocoders.
GoogleCoder(**kwargs)	Uses the Google Geocoding API, via the geopy.geocoders.GoogleV3 coder.
YahooCoder(yahoo_id, **kwargs)	Uses the Yahoo PlaceMaker API.

class tethne.services.geocode.BaseCoder(**kwargs)

Bases: object

Base class for geocoders.

code_list(placenames)

Retrieve Location for a list of placenames.

Parameters:

placenames : list

Returns:

locations : dict

Placename - Location mapping.

code_this(placename)

Retrieve a Location for a placename.

Parameters:placename : str or unicode Returns:location : Location

max_tries = 3

persistent = True

sleep_interval = 0.5

timeout = 3

class tethne.services.geocode.GoogleCoder(**kwargs)

Bases: tethne.services.geocode.BaseCoder

Uses the Google Geocoding API, via the geopy.geocoders.GoogleV3 coder.

classmethod code(query, exactly_one=True, timeout=None, bounds=None, region=None, components=None, language=None, sensor=False)

Geocode a location query.

Parameters:

• query (string) – The address or query you wish to geocode.
• exactly_one (bool) – Return one result or a list of results, if available.
• timeout (int) –

  Time, in seconds, to wait for the geocoding service to respond before raising a geopy.exc.GeocoderTimedOut exception. Set this only if you wish to override, on this call only, the value set during the geocoder’s initialization.

  New in version 0.97.

• bounds (list or tuple) – The bounding box of the viewport within which to bias geocode results more prominently.
• region (string) – The region code, specified as a ccTLD (“top-level domain”) two-character value.
• components (dict) –

  Restricts to an area. Can use any combination of: route, locality, administrative_area, postal_code, country.

  New in version 0.97.1.

• language (string) – The language in which to return results.
• sensor (bool) – Whether the geocoding request comes from a device with a location sensor.

coder = <geopy.geocoders.googlev3.GoogleV3 object at 0x109425c90>

get_location(response)

Yields Location based on a response from Google Geocoding API.

Parameters:

response : tuple

GoogleV3 geocoder response: (u’Name’, (Lat, Lon))

Returns:

location : Location

class tethne.services.geocode.Location(place='', latitude=0.0, longitude=0.0, **kwargs)

Bases: object

Minimal geographic datum yielded by geocoders.

latitude = 0.0

longitude = 0.0

place = ''

class tethne.services.geocode.YahooCoder(yahoo_id, **kwargs)

Bases: tethne.services.geocode.BaseCoder

Uses the Yahoo PlaceMaker API.

code(name)

Constructs and sends a Yahoo PlaceMaker API query.

Parameters:name : string Returns:HTTPResponse

get_location(response)

Yields Location based on a response from Yahoo PlaceMaker API.

Parameters:response : HTTPResponse Returns:location : Location

lat_searchpath = './/{http://where.yahooapis.com/v1/schema.rng}centroid/{http://where.yahooapis.com/v1/schema.rng}latitude'

lon_searchpath = './/{http://where.yahooapis.com/v1/schema.rng}centroid/{http://where.yahooapis.com/v1/schema.rng}longitude'

name_searchpath = './/{http://where.yahooapis.com/v1/schema.rng}name'

yahoo_base = 'http://where.yahooapis.com/v1/places'