services Package

services Package

Modules for interacting with external web services.

geocode

This module provides classes for geocoding bibliographic data.

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.

Methods

code_list(placenames)	Retrieve Location for a list of placenames.
code_this(placename)	Retrieve a Location for a placename.

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.

Methods

code(query[, bounds, region, language, ...])	Geocode a location query.
code_list(placenames)	Retrieve Location for a list of placenames.
code_this(placename)	Retrieve a Location for a placename.
get_location(response)	Yields Location based on a response from Google Geocoding API.

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

Geocode a location query.

Parameters:

• query (string) – The address or query you wish to geocode.
• 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.
• language (string) – The language in which to return results.
• sensor (bool) – Whether the geocoding request comes from a device with a location sensor.
• 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.

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

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.

Methods

code(name)	Constructs and sends a Yahoo PlaceMaker API query.
code_list(placenames)	Retrieve Location for a list of placenames.
code_this(placename)	Retrieve a Location for a placename.
get_location(response)	Yields Location based on a response from 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'