Metadata-Version: 2.1
Name: placekey
Version: 0.0.8
Summary: Utilities for working with Placekeys
Home-page: https://github.com/Placekey/placekey-py
Author: SafeGraph Inc.
Author-email: russ@safegraph.com
License: UNKNOWN
Description: # Placekey-py
        
        [![PyPI version](https://badge.fury.io/py/placekey.svg)](https://badge.fury.io/py/placekey)
        [![PyPI downloads](https://img.shields.io/pypi/dm/placekey)](https://pypistats.org/packages/placekey)
        [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
        
        A Python library for working with [Placekeys](https://placekey.io). Documentation for this package can be found [here](https://placekey.github.io/placekey-py/), and documentation for the Placekey service API can be found [here](https://docs.placekey.io/). The Plackey design specification is available [here](https://docs.placekey.io/Placekey_Technical_White_Paper.pdf). The details in Placekey encoding is [here](https://docs.placekey.io/Placekey_Encoding_Specification%20White_Paper.pdf). We welcome your feedback. 
        
        ## Installation
        
        This package can be installed from [PyPI](https://pypi.org/project/placekey/) by
        
        ```shell script
        pip install placekey
        ```
        
        ## Usage
        
        The basic functionality of the Placekey library is conversion between Placekeys and latitude-longitude coordinates.
        
        ```python
        >>> import placekey as pk
        >>> lat, long = 0.0, 0.0
        >>> pk.geo_to_placekey(lat, long)
        '@dvt-smp-tvz'
        ```
        
        ```python
        >>> pk.placekey_to_geo('@dvt-smp-tvz')
        (0.00018033323813810344, -0.00018985758738881587)
        ```
        
        The library also allows for conversion between Placekeys and [H3 indices](https://github.com/uber/h3-py).
        
        ```python
        >>> pk.placekey_to_h3('@dvt-smp-tvz')
        '8a754e64992ffff'
        ```
        
        ```python
        >>> pk.h3_to_placekey('8a754e64992ffff')
        '@dvt-smp-tvz'
        ```
        
        The distance in meters between two Placekeys can be found with the following function.
        
        ```python
        >>> 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()`.
        
        ```python
        >>> 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
        
        ```python
        >>> pk.placekey_format_is_valid('222-227@dvt-smp-tvz')
        True
        ```
        
        ```python
        >>> 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.
        
        ```python
        >>> 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.
        
        ```python
        >>> pk_api.lookup_placekey(latitude=37.7371, longitude=-122.44283)
        {'query_id': '0', 'placekey': '@5vg-82n-kzz'}
        ```
        
        ```python
        >>> 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.
        
        ```python
        >>> 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](https://docs.placekey.io/).
        
        ## Notebooks
        
        Jupyter notebooks demonstrating various Placekey functionality are contained in the [placekey-notebooks](https://github.com/Placekey/placekey-notebooks) repository.
        
        ## Support
        
        This package runs on Python 3.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
