Placekey-py

A Python library for working with Placekeys. Documentation for this package can be found here, and documentation for the Placekey service API can be found here. The Plackey design specification is available here. The details in Placekey encoding is here. We welcome your feedback.

Installation

This package can be installed from PyPI by

pip  install  placekey

MacOS Big Sur may need to run brew install geos if the installation of the shapely dependency fails.

Usage

The basic functionality of the Placekey library is conversion between Placekeys and latitude-longitude coordinates.

>>> import placekey as pk

>>> lat, long = 0.0, 0.0

>>> pk.geo_to_placekey(lat, long)

'@dvt-smp-tvz'

>>> pk.placekey_to_geo('@dvt-smp-tvz')

(0.00018033323813810344, -0.00018985758738881587)

The library also allows for conversion between Placekeys and H3 indices.

>>> pk.placekey_to_h3('@dvt-smp-tvz')

'8a754e64992ffff'

>>> pk.h3_to_placekey('8a754e64992ffff')

'@dvt-smp-tvz'

The distance in meters between two Placekeys can be found with the following function.

>>> pk.placekey_distance('@dvt-smp-tvz', '@5vg-7gq-tjv')

12795124.895573696

An upper bound on the maximal distance in meters between two Placekeys based on the length of their shared prefix is provided by placekey.get_prefix_distance_dict().

>>> pk.get_prefix_distance_dict()

{0: 20040000.0,

1: 20040000.0,

2: 2777000.0,

3: 1065000.0,

4: 152400.0,

5: 21770.0,

6: 8227.0,

7: 1176.0,

8: 444.3,

9: 63.47}

Placekeys found in a data set can be partially validated by

>>> pk.placekey_format_is_valid('222-227@dvt-smp-tvz')

True

>>> pk.placekey_format_is_valid('@123-456-789')

False

You can now access the locations of placekey’s free datasets in S3 using placekey-py! Use these two functions:

print(pk.list_free_datasets())
print(pk.return_free_datasets_location_by_name('chipotle-locations'))

1. List Free Datasets: Returns a list of all names of Placekey’s available free datasets

2. Return Free Datasets Location By Name: Using one of the names from List Free Datasets above, returns the publicly accessible S3 URI of said dataset.

You can use these locations to download files programmatically (with boto3) or directly in Spark.

API Client

This package also includes a client for the Placekey API. The methods in the client are automatically rate limited.

>>> from placekey.api import PlacekeyAPI

>>> placekey_api_key = "..."

>>> pk_api = PlacekeyAPI(placekey_api_key)

The PlacekeyAPI.lookup_placekey method can be used to lookup the Placekey for a single place.

>>> pk_api.lookup_placekey(latitude=37.7371, longitude=-122.44283)

{'query_id': '0', 'placekey': '@5vg-82n-kzz'}

>>> place = {

>>> "location_name": "Twin Peaks Petroleum",

>>> "street_address": "598 Portola Dr",

>>> "city": "San Francisco",

>>> "region": "CA",

>>> "postal_code": "94131",

>>> "iso_country_code": "US"

>>> }

>>> pk_api.lookup_placekey(**place, fields="building_placekey","address_placekey","confidence_score","gers", "address_confidence_score"])

{
'query_id': '0', 
'placekey': '227-223@5vg-82n-pgk', 
'address_placekey': '227@5vg-82n-pgk', 
'building_placekey': '227@5vg-82n-pgk', 
'confidence_score': 'HIGH', 
'address_confidence_score': 'HIGH', 
'gers': None
}

The PlacekeyAPI.lookup_placekeys method can be used to lookup Placekeys for multiple places.

>>> places = [

>>> {

>>> "street_address": "1543 Mission Street, Floor 3",

>>> "city": "San Francisco",

>>> "region": "CA",

>>> "postal_code": "94105",

>>> "iso_country_code": "US"

>>> },

>>> {

>>> "query_id": "thisqueryidaloneiscustom",

>>> "location_name": "Twin Peaks Petroleum",

>>> "street_address": "598 Portola Dr",

>>> "city": "San Francisco",

>>> "region": "CA",

>>> "postal_code": "94131",

>>> "iso_country_code": "US"

>>> },

>>> {

>>> "latitude": 37.7371,

>>> "longitude": -122.44283

>>> }

>>> ]

>>> pk_api.lookup_placekeys(places, fields=["building_placekey","address_placekey","confidence_score","gers"])

[{'query_id': 'place_0',

'placekey': '0rsdbudq45@5vg-7gq-5mk',

'address_placekey': '0rsdbudq45@5vg-7gq-5mk',

'building_placekey': '22g@5vg-7gq-5mk',

'confidence_score': 'HIGH',

'gers': None},

{'query_id': 'thisqueryidaloneiscustom',

'placekey': '227-223@5vg-82n-pgk',

'address_placekey': '227@5vg-82n-pgk',

'building_placekey': '227@5vg-82n-pgk',

'confidence_score': 'HIGH',

'gers': None},

{'query_id': 'place_2',

'placekey': '@5vg-82n-kzz',

'confidence_score': 'HIGH',

'gers': None}]

You can submit a Pandas dataset and have it come back placekey'd:

df  =  pd.DataFrame({
"address": ["1543 Mission Street, Floor 3", "598 Portola Dr", None],
"city": ["San Francisco", "San Francisco", None],
"region": ["CA", "CA", None],
"postal": ["94105", "94131", None],
"country": ["US", "US", None],
"latitude": [None, None, 37.7371],
"longitude": [None, None, -122.44283]
})

column_mappings  = {
"street_address": "address",
"city": "city",
"region": "region",
"postal_code": "postal",
"iso_country_code": "country",
"latitude": "latitude",
"longitude": "longitude"
}

df_with_placekeys  =  pk_api._placekey_pandas_df(df, column_mappings, fields=['address_placekey', 'address_confidence_score'])
print(df_with_placekeys)

                       address           city region postal country  latitude  longitude         placekey address_placekey
0  1543 Mission Street, Floor 3  San Francisco     CA  94105      US       NaN        NaN  22g@5vg-7gq-5mk  22g@5vg-7gq-5mk
1                598 Portola Dr  San Francisco     CA  94131      US       NaN        NaN  227@5vg-82n-pgk  227@5vg-82n-pgk
2                          None           None   None   None    None   37.7371 -122.44283     @5vg-82n-kzz              NaN

You can also join two pandas datasets together (placekey'd or not).

join  =  pk_api._join_pandas_df(df_1, column_mappings_1, df_2, column_mappings_2, on='address_placekey', how='outer')

Full details on how to query the API and how to get an API key can be found here.

Notebooks

Jupyter notebooks demonstrating various Placekey functionality are contained in the placekey-notebooks repository.

Support

This package runs on Python 3.