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: about 2 months 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 (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-02-24T22:09:44.000Z (8 months ago)
- Last Synced: 2025-07-04T10:55:29.165Z (4 months ago)
- Topics: api, api-client, conversion, distance, geospatial, h3, placekey, placekey-api, pypi
- Language: Python
- Homepage: https://placekey.io
- Size: 2.97 MB
- Stars: 62
- Watchers: 3
- Forks: 8
- Open Issues: 7
-
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
```
You can now access the locations of placekey’s free datasets in S3 using placekey-py! Use these two functions:
```python
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.
```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", "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.
```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}]
```
You can submit a Pandas dataset and have it come back wth Placekeys:
```python
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).
```python
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](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.