# Python

## Placekey-py

The Placekey Python library makes it easy to work with Placekey. Detailed documentation for this package can be found [here](https://placekey.github.io/placekey-py/). This package runs on Python 3.

## Installation

This package can be installed from PyPI by

```bash
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 dataset 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"])
{'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.

```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': 'place_0', 'placekey': '22g@5vg-7gq-5mk'},
 {'query_id': 'thisqueryidaloneiscustom', 'placekey': '227-223@5vg-82n-pgk'},
 {'query_id': 'place_2', 'placekey': '@5vg-82n-kzz'}]
```

## Notebooks

Jupyter notebooks demonstrating various Placekey functionality are contained in the [placekey-notebooks](https://github.com/Placekey/placekey-notebooks) repository.

## Additional Information

More information about this library can be found on [Github](https://github.com/Placekey/placekey-py) where you can also submit pull requests, submit bugs, and feature suggestions.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.placekey.io/documentation/libraries/python.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.