Skip to main content

Utilities for working with Placekeys

Project description

Placekey-py

PyPI version PyPI downloads version

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

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

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 = {
>>>   "street_address": "598 Portola Dr",
>>>   "city": "San Francisco",
>>>   "region": "CA",
>>>   "postal_code": "94131",
>>>   "iso_country_code": "US"
>>> }
>>> pk_api.lookup_placekey(**place, strict_address_match=True)
{'query_id': '0', 'placekey': '227@5vg-82n-pgk'}

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)
[{'query_id': '0', 'placekey': '226@5vg-7gq-5mk'},
 {'query_id': 'thisqueryidaloneiscustom', 'placekey': '227-222@5vg-82n-pgk'},
 {'query_id': '2', 'placekey': '@5vg-82n-kzz'}]

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for placekey, version 0.0.6
Filename, size File type Python version Upload date Hashes
Filename, size placekey-0.0.6.tar.gz (10.3 kB) File type Source Python version None Upload date Hashes View
Filename, size placekey-0.0.6-py2-none-any.whl (13.6 kB) File type Wheel Python version py2 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page