mapper - Geocoding, Local Search, Directions, Routes

Geocoding, local search, directions, route iterator, and related functions.

class Mapper(api_key='', referrer_url='')

Abstracts converting addresses to latitude/longitude and vice versa; finding points of interest; getting directions from one point to another; and iterating over routes between lists of points.

Initializes this Mapper with a given API key and referrer_url.

Parameters:

• api_key (string) – Google Maps API key
• referrer_url (string) – URL of the website that will be making the queries.

addr_to_latlng(addr)

Convert an address to latitude and longitude.

Parameter:addr (string) – Address to convert Returns:(latitude, longitude) tuple Return type:(float, float) Raises MapperError:  If addr could not be geocoded.

directions(origin, destination)

Return a dictionary of information about the route from origin to destination.

Parameters:

• origin (string) – Starting address
• destination (string) – Ending address

Returns:

Dictionary of information about the overall route from origin to destination with the following keys: meters, seconds, steps, start, end.

Return type:

dict(string: numeric or string)

Raises MapperError:  

If the method was unable to find directions.

>>> mapper = Mapper()
>>> dirs = mapper.directions('San Diego, CA', 'Los Angeles, CA')
>>> for k, v in sorted(dirs.iteritems()):
...    print "%s: %s" % (k, v)
end: Los Angeles, CA
meters: 193463
seconds: 7024
start: San Diego, CA
steps: 6

get_listings(query, city, num=8, err_callback=None)

Perform a local search to find points of interest in a given city.

Listings are normalized by geocoding; if a point cannot be normalized, it is skipped. Thus, this method may return fewer listings than requested.

Parameters:

• query (string) – Name or type of place you are looking for, e.g. ‘soul food’, ‘starbucks’
• city (string) – City (or any locale, really) in which to search
• numpoints (int) – The number of results to return
• err_callback (func(string)) – Function that will be called with the text of any error messages.

Returns:

list of Listing dictionaries.

Return type:

list of dict(string: string or float) with the following keys: name, address, street, city, region, postcode, country, lat, lng, url

Raises MapperError:  

If the query or city was bad.

>>> mapper = Mapper()
>>> listings = mapper.get_listings('soul food', 'harlem, ny', num=1)
>>> for k, v in sorted(listings[0].iteritems()):
...    print "%s: %s" % (k, v)
address: 113 W 116th St, New York, NY 10026, USA
city: New York
country: US
lat: 40.8023467
lng: -73.9504037
name: Amy Ruth's Restaurant
postcode: 10026
region: NY
street: 113 W 116th St
url: http://www.google.com/local?source=uds&q=soul+food&sll=40.802346%2C-73.950403&latlng=40802346%2C-73950403%2C414659386583196097&near=40.802346%2C-73.950403

latlng_to_addr(latlng)

Convert latitude and longitude to a street address.

Parameter:latlng ((float, float)) – (latitude, longitude) tuple Returns:Closest street address to latlng Return type:string Raises MapperError:  If there was no street address close to latlng

normalize_addr(addr)

Return the canonical, normalized form of an address as a dict.

Parameter:addr (string) – Address to normalize. Returns:Dictionary with the following keys: address, street, city, region, postcode, country, lat, lng. Return type:dict(string: string or float) Raises MapperError:  If the address could not be normalized.

>>> mapper = Mapper()
>>> addr =  mapper.normalize_addr('1-4573 Chateau Boulevard RR 4 Whistler, BC V0N 1B4, Canada')
>>> for k, v in sorted(addr.iteritems()):
...    print "%s: %s" % (k, v)
address: 4573 Chateau Blvd, Whistler, BC, Canada
city: Whistler
country: CA
lat: 50.1174596
lng: -122.9466722
postcode: V0N
region: BC
street: 4573 Chateau Blvd

routes(from_addrs, to_addrs, callback=None, sleep_secs=0.5)

Yield route driving information for all pairs of addresses from from_addrs to to_addrs.

Try to compute a route from every address in from_addrs to every listing in to_addrs (len(from_points) * len(to_points) routes in total).

Parameters:

• from_addrs (list(string)) – list of starting addresses for routes
• to_addrs (list(string)) – list of ending addresses for routes
• callback (func(string)) – Function that you supply, will be called periodically with a string giving the current status of the operation.
• sleep_secs (float) – Seconds to sleep between each iteration so’s you don’t burn up your query limit.

Returns:

list of dictionaries giving start, end, meters, seconds, and steps for each route.

Return type:

(generator of) list(dict(string: string or numeric))

Raises MapperError:  

If there are too many consecutive errors in retrieving route directions.

>>> mapper = Mapper()
>>> from_points = mapper.get_listings('elementary school', 'boston, ma', num=2)
>>> from_addrs = [point['address'] for point in from_points]
>>> to_points = mapper.get_listings('starbucks', 'boston, ma', num=1)
>>> to_addrs = [point['address'] for point in to_points]
>>> for route in mapper.routes(from_addrs, to_addrs):
...    print "Route:"
...    for k, v in sorted(route.iteritems()):
...        print "  %s: %s" % (k, v)
Route:
  end: 222 Cambridge St, Boston, MA 02114, USA
  meters: 1702
  seconds: 302
  start: 16 Charter St, Boston, MA 02113, USA
  steps: 6
Route:
  end: 222 Cambridge St, Boston, MA 02114, USA
  meters: 1294
  seconds: 141
  start: 67 Brimmer St, Boston, MA 02108, USA
  steps: 7

exception MapperError(message, code=None)

Base class for errors in the mapper module.

Methods of class Mapper raise this when something goes wrong. Don’t depend on the exact string of the error message, because they’re implementation-dependent.

Create an exception with a message and optional status code.

Parameters:

• message – Message explaining the exception.
• status (int) – OK, SEVER_ERROR, UNKNOWN_ADDRESS, BAD_QUERY, or TOO_FAST

km_to_degrees_latitude(dist)

Converts distance in km (at any latitude or longitude) to degrees latitude.

Assumes earth is a big sphere.

Parameter:dist (float) – distance in kilometers Returns:dist in degrees latitude Return type:float

km_to_degrees_longitude(dist, lat)

Converts distance in km at a given latitude into degrees longitude.

Degrees longitude represent less (East-West) distance as you move away from the equator. Assumes earth is a big sphere.

Parameters:

• dist (float) – distance in kilometers at latitude lat
• lat (float) – degrees latitude at which to measure distance dist

Returns:

Distance in degrees longitude at the given latitude

Return type:

float

Indices and tables

• Index
• Module Index
• Search Page