Metadata-Version: 2.4
Name: kuid-sdk
Version: 1.0.0
Summary: Official Python SDK for the KUID API.
Author-email: KUID <ndeasdigital@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://kuid.me
Project-URL: Documentation, https://kuid.me/docs
Project-URL: Repository, https://github.com/ndeascloud/kuid-plataform
Project-URL: Issues, https://github.com/ndeascloud/kuid-plataform/issues
Keywords: kuid,geolocation,address
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Dynamic: license-file

# KUID SDK for Python

Official Python SDK for the KUID API.

## Install

```bash
pip install kuid-sdk
```

## Quick start

```python
from kuid_sdk import KuidClient

client = KuidClient("YOUR_API_KEY")
address = client.get_address("AO-LUA-CAC-KDIA")

print(address.to_dict())
print(client.get_navigation_url(address.latitude, address.longitude))
```

## Normalized response

```python
{
    "kuid": "AO-LUA-CAC-KDIA",
    "address": "Avenida Deolinda Rodrigues",
    "latitude": -8.82,
    "longitude": 13.24,
}
```

## Features

- `KuidClient` as the main entrypoint.
- `get_address(kuid)` with KUID validation.
- In-memory cache with a 5 minute TTL.
- Typed exceptions for invalid input, API failures, network failures, and parsing issues.
- `get_navigation_url(lat, lng)` helper.

## Error handling

```python
from kuid_sdk import InvalidKuidError, KuidApiError, KuidClient

client = KuidClient("YOUR_API_KEY")

try:
    client.get_address("AO-LUA-CAC-KDIA")
except InvalidKuidError as error:
    print(error)
except KuidApiError as error:
    print(error.status_code, error)
```

## Run the example

```bash
set KUID_API_KEY=YOUR_API_KEY
python examples/basic_usage.py
```

## Run tests

```bash
python -m unittest discover -s tests
```
```
