Docs
  • 👋Welcome
    • Overview
    • Placekey Design
    • Placekey Types
  • API Overview
    • Authentication
    • Usage Limits
    • Error Codes
    • Supported Countries
  • Placekey API
    • Quick Start
    • Input Parameters
      • Minimum Inputs
      • Optional Parameters
    • Response
      • Optional Responses
    • Bulk API
    • Example Queries
    • Placekey Lineage File
  • Geocoder
    • Introduction
    • Usage Limit
    • Status Descriptions
    • Example
  • Join Data Product
    • Join Data
  • Libraries
    • Python
    • Javascript
  • Integrations
    • Google Sheets Add On
Powered by GitBook
On this page
  • Placekey-py
  • Installation
  • Usage
  • API Client
  • Notebooks
  • Additional Information
  1. Libraries

Python

PreviousJoin Data NextJavascript

Placekey-py

The Placekey Python library makes it easy to work with placekey. Detailed documetnation for this package can be found . This package runs on Python 3.

Installation

This package can be installed from PyPl by

pip install placekey

MacOS Big Sur may need to run the following if the installation of the shapely dependency fails

brew install geos

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 .

>>> 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 dataset 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 = {
>>>   "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"])
{'query_id': '0',
 'placekey': '227-223@5vg-82n-pgk',
 'address_placekey': '227@5vg-82n-pgk',
 'building_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': 'place_0', 'placekey': '226@5vg-7gq-5mk'},
 {'query_id': 'thisqueryidaloneiscustom', 'placekey': '227-222@5vg-82n-pgk'},
 {'query_id': 'place_2', 'placekey': '@5vg-82n-kzz'}]

Notebooks

Additional Information

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

More information about this library can be found on where you can also submit pull requests, submit bugs, and feature suggestions.

here
H3 indices
placekey-notebooks
Github