Submodules

placekey.api

class placekey.api.PlacekeyAPI(api_key=None, max_retries=20, logger=<RootLogger root (ERROR)>, user_agent_comment=None)[source]

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)

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_batch(places, strict_address_match=False, strict_name_match=False)[source]

Lookup Placekeys for a single batch of places specified by place dictionaries. The batch size can be at most 100 places. This method respects the rate limits of the Placekey API.

Parameters
  • places – An iterable of of place dictionaries.

  • strict_address_match – Boolean for whether or not to strict match on address fields. Defaults to False.

  • strict_name_match – Boolean for whether or not to strict match on location_name. Defaults to False.

Returns

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

lookup_placekey(strict_address_match=False, strict_name_match=False, **kwargs)[source]

Lookup the Placekey for a single place.

Parameters
  • strict_address_match – Boolean for whether or not to strict match on address fields. Defaults to False.

  • strict_name_match – Boolean for whether or not to strict match on location_name. Defaults to False.

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’]

Returns

A Placekey API response (dict)

lookup_placekeys(places, strict_address_match=False, strict_name_match=False, batch_size=100, verbose=False)[source]

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.

  • strict_address_match – Boolean for whether or not to strict match on address fields. Defaults to False.

  • strict_name_match – Boolean for whether or not to strict match on location_name. Defaults to False.

  • 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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

Convert an H3 integer into a Placekey.

Parameters

h3_integer – H3 index (int)

Returns

Placekey (string)

placekey.placekey.h3_to_placekey(h3_string)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Convert a Placekey string into an H3 string.

Parameters

placekey – Placekey (string)

Returns

H3 (string)

placekey.placekey.placekey_to_h3_int(placekey)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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