Submodules

placekey.api

class placekey.api.PlacekeyAPI(api_key=None, max_retries=20, logger=<Logger placekey.api (ERROR)>, user_agent_comment=None)

Bases: object

PlacekeyAPI class

This class provides functionality for looking up Placekeys using the Placekey API. Places to be looked a specified by a place dictionary whose keys and value types must be a subset of

• latitude (float)

• longitude (float)

• location_name (string)

• street_address (string)

• city (string)

• region (string)

• postal_code (string)

• iso_country_code (string)

• query_id (string)

• place_metadata (dict[str,str])

See the Placekey API documentation for more information on how to use the API.

Parameters:

• api_key – Placekey API key (string)

• max_retries – Maximum number of times to retry a failed request before halting (int). Backoffs due to rate-limiting are included in the retry count. Defaults to 20.

• logger – A logging object. Logs are sent to the console by default.

• user_agent_comment – A string to append to the client’s user agent, which will be “placekey-py/{version_number} {user_agent_comment}.

lookup_placekey(fields=None, **kwargs)

Lookup the Placekey for a single place.

Kwargs:

Place fields can be passed to this method as keyword arguments. The allowed keyword arguments are [‘latitude’, ‘longitude’, ‘location_name’,’street_address’, ‘city’, ‘region’, ‘postal_code’, ‘iso_country_code’, ‘query_id’, ‘place_metadata’]

Returns:

A Placekey API response (dict)

lookup_placekeys(places, fields=None, batch_size=100, verbose=False)

Lookup Placekeys for an iterable of places specified by place dictionaries. This method checks that the place dictionaries are valid before querying the API, and it will return partial results if it encounters a fatal error. Places without a query_id will have one generated for them based on their index in places, e.g., “place_0” for the first item in the list, but a user-provided query_id will be passed through as is.

This function is a wrapper for lookup_batch, and that function may be used if different error handling or logic around batch processing is desired.

This method follows the rate limits of the Placekey API.

Parameters:

• places – An iterable of of place dictionaries.

• fields – A list of requested parameters other than placekey. For example: address_placekey, building_placekey Defaults to None

• batch_size – Integer for the number of places to lookup in a single batch. Defaults to 100, and cannot exceeded 100.

• verbose – Boolean for whether or not to log additional information. Defaults to False

Returns:

A list of Placekey API responses for each place (list(dict))

placekey.placekey

Functionality for converting between Placekeys and geos (latitude, longitude tuples) or H3 indices. This module also includes additional utilities related to Placekeys.

placekey.placekey.geo_to_placekey(lat, long)

Convert latitude and longitude into a Placekey.

Parameters:

• lat – Latitude (float)

• long – Longitude (float)

Returns:

Placekey (string)

placekey.placekey.geojson_to_placekeys(geojson, include_touching=False, geo_json=True)

Given a GeoJSON description of a polygon, return Placekeys contained in or intersecting the boundary of the polygon.

Parameters:

• geo_json – GeoJSON object (string or dict). Note this function assumes coordinate tuples are (long, lat)

• include_touching – If True Placekeys whose hexagon boundary only touches that of the input polygon are included in the set of boundary Placekeys. Default is False.

• geo_json – If True (default) assume coordinates in poly are in GeoJSON format: (long, lat)-tuples and with the first and last tuples identical, and in counter-clockwise orientation. If False assumes tuples will be (lat, long).

Returns:

List of Placekeys

placekey.placekey.get_neighboring_placekeys(placekey, dist=1)

Return the unordered set of Placekeys whose grid distance is <= dist from the given Placekey. In this context, grid distance refers to the number of H3 cells between two H3 cells, so that neighboring cells have distance 1, neighbors of neighbors have distance 2, etc.

Parameters:

• placekey – Placekey (string)

• dist – size of the neighborhood around the input Placekey to return (int)

Returns:

Set of Placekeys (set)

placekey.placekey.get_prefix_distance_dict()

Return a dictionary mapping the length of a shared Placekey prefix to the maximal distance in meters between two Placekeys sharing a prefix of that length.

Returns:

Dictionary mapping prefix length -> distance (m)

placekey.placekey.h3_int_to_placekey(h3_integer)

Convert an H3 integer into a Placekey.

Parameters:

h3_integer – H3 index (int)

Returns:

Placekey (string)

placekey.placekey.h3_to_placekey(h3_string)

Convert an H3 hexadecimal string into a Placekey string.

Parameters:

h3_string – H3 (string)

Returns:

Placekey (string)

placekey.placekey.placekey_distance(placekey_1, placekey_2)

Return the distance in meters between the centers of two Placekeys.

Parameters:

• placekey_1 – Placekey (string)

• placekey_2 – Placekey (string)

Returns:

distance in meters (float)

placekey.placekey.placekey_format_is_valid(placekey)

Boolean for whether or not the format of a Placekey is valid, including checks for valid encoding of location.

Parameters:

placekey – Placekey (string)

Returns:

True if the Placekey is valid, False otherwise

placekey.placekey.placekey_to_geo(placekey)

Convert a Placekey into a (latitude, longitude) tuple.

Parameters:

placekey – Placekey (string)

Returns:

(latitude, longitude) as a tuple of floats

placekey.placekey.placekey_to_geojson(placekey)

Convert a Placekey into a GeoJSON dicitonary. Note that GeoJSON uses (longitude, latitude) points, and the first and last points are identical.

Parameters:

placekey – Placekey (string)

Returns:

Dictionary describing the polygon in GeoJSON format

placekey.placekey.placekey_to_h3(placekey)

Convert a Placekey string into an H3 string.

Parameters:

placekey – Placekey (string)

Returns:

H3 (string)

placekey.placekey.placekey_to_h3_int(placekey)

Convert a Placekey to an H3 integer.

Parameters:

placekey – Placekey (string)

Returns:

H3 index (int)

placekey.placekey.placekey_to_hex_boundary(placekey, geo_json=False)

Given a Placekey, return the coordinates of the boundary of the hexagon.

Parameters:

• placekey – Placekey (string)

• geo_json – If True return the coordinates in GeoJSON format: (long, lat)-tuples and with the first and last tuples identical, and in counter-clockwise orientation. If False (default) tuples will be (lat, long), the last tuple will not equal the first, and the orientation will be clockwise.

Returns:

Tuple of tuples ((float, float),…).

placekey.placekey.placekey_to_polygon(placekey, geo_json=False)

Get the boundary shapely Polygon for a Placekey.

Parameters:

• place_key – Placekey (string)

• geo_json – If True return the coordinates in GeoJSON format: (long, lat)-tuples and with the first and last tuples identical, and in counter-clockwise orientation. If False (default) tuples will be (lat, long), the last tuple will not equal the first, and the orientation will be clockwise.

Returns:

A shapely Polygon object

placekey.placekey.placekey_to_wkt(placekey, geo_json=False)

Convert a Placekey into the WKT (Well-Known Text) string for the corresponding hexagon. Coordinates are (longitude, latitude).

Parameters:

• placekey – Placekey (string)

• geo_json – If True return the coordinates in GeoJSON format: (long, lat)-tuples and with the first and last tuples identical, and in counter-clockwise orientation. If False (default) tuples will be (lat, long), the last tuple will not equal the first, and the orientation will be clockwise.

Returns:

WKT (Well-Known Text) polygon (string)

placekey.placekey.polygon_to_placekeys(poly, include_touching=False, geo_json=False)

Given a shapely Polygon, return Placekeys contained in or intersecting the boundary of the polygon.

Parameters:

• poly – shapely Polygon object

• include_touching – If True Placekeys whose hexagon boundary only touches that of the input polygon are included in the set of boundary Placekeys. Default is False.

• geo_json – If True assume coordinates in poly are in GeoJSON format: (long, lat)-tuples and with the first and last tuples identical, and in counter-clockwise orientation. If False (default) assumes tuples will be (lat, long).

Returns:

A dictionary with keys ‘interior’ and ‘boundary’ whose values are tuples of Placekeys that are contained in poly or which intersect the boundary of poly respectively.

placekey.placekey.wkt_to_placekeys(wkt, include_touching=False, geo_json=False)

Given a WKT description of a polygon, return Placekeys contained in or intersecting the boundary of the polygon.

Parameters:

• wkt – Well-Known Text object (string)

• include_touching – If True Placekeys whose hexagon boundary only touches that of the input polygon are included in the set of boundary Placekeys. Default is False.

• geo_json – If True assume coordinates in poly are in GeoJSON format: (long, lat)-tuples and with the first and last tuples identical, and in counter-clockwise orientation. If False (default) assumes tuples will be (lat, long).

Returns:

List of Placekeys