Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Placekey/placekey-py
https://github.com/Placekey/placekey-py
api api-client conversion distance geospatial h3 placekey placekey-api pypi
Last synced: 17 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/Placekey/placekey-py
- Owner: Placekey
- License: apache-2.0
- Created: 2020-09-28T07:00:33.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-06-18T16:32:06.000Z (3 months ago)
- Last Synced: 2024-08-19T17:29:38.653Z (about 1 month ago)
- Topics: api, api-client, conversion, distance, geospatial, h3, placekey, placekey-api, pypi
- Language: Python
- Homepage: https://placekey.io
- Size: 3.02 MB
- Stars: 58
- Watchers: 4
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Placekey-py
[](https://badge.fury.io/py/placekey)
[](https://pypistats.org/packages/placekey)
[](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
```
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.
```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 = {
>>> "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"])
{'query_id': '0',
'placekey': '227-223@5vg-82n-pgk',
'address_placekey': '227@5vg-82n-pgk',
'building_placekey': '227@5vg-82n-pgk',
'confidence_score': 'HIGH',
'gers': None}
```
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, 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}]
```
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.