> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prontiq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Python client for the Prontiq API, published as prontiq on PyPI.

## Installation

```bash theme={null}
pip install prontiq
```

The package is published on [PyPI](https://pypi.org/project/prontiq/) and the
generated SDK source is available at
[github.com/prontiq/prontiq-python](https://github.com/prontiq/prontiq-python).

## Setup

Set your API key in the environment:

```bash theme={null}
export PRONTIQ_API_KEY="YOUR_API_KEY"
```

Then create a client:

```python theme={null}
import os
from prontiq import Prontiq

client = Prontiq(
    api_key=os.environ.get("PRONTIQ_API_KEY"),
)
```

`api_key` defaults to `PRONTIQ_API_KEY`, so you can omit it when that
environment variable is set.

## Autocomplete

```python theme={null}
response = client.address.autocomplete(
    q="200 George Street Sydney",
)
# response.total is the number of suggestions returned.

for suggestion in response.suggestions:
    print(
        suggestion.address_label,
        suggestion.prontiq_match_score,
        suggestion.prontiq_match_quality,
    )
```

## Validate

```python theme={null}
response = client.address.validate(
    q="200 George Street Sydney",
)

if response.prontiq_match_quality == "high":
    print(f"Verified: {response.match.address_label if response.match else None}")
```

## Enrich

```python theme={null}
response = client.address.enrich(
    id="GAQLD156786950",
)

print(response.geocode)
print(response.components.street_number_first if response.components else None)
print(response.boundaries.sa1 if response.boundaries else None)
print(response.aliases or [])
```

## Async usage

Use `AsyncProntiq` for async applications:

```python theme={null}
import asyncio
import os
from prontiq import AsyncProntiq

client = AsyncProntiq(
    api_key=os.environ.get("PRONTIQ_API_KEY"),
)


async def main() -> None:
    response = await client.address.autocomplete(
        q="200 George Street Sydney",
    )
    print(response.suggestions)


asyncio.run(main())
```

## Error handling

All SDK errors inherit from `prontiq.APIError`.

```python theme={null}
import prontiq
from prontiq import Prontiq

client = Prontiq()

try:
    client.address.autocomplete(q="200 George Street Sydney")
except prontiq.APIConnectionError as err:
    print("Could not reach Prontiq")
    print(err.__cause__)
except prontiq.RateLimitError:
    print("Rate limited; retry after the server-provided delay when present.")
except prontiq.APIStatusError as err:
    print(err.status_code)
    print(err.response)
```

## More methods

The Python SDK is generated from the public OpenAPI spec. See the generated
[SDK repository](https://github.com/prontiq/prontiq-python) for the full client
API.

| Method                                                                               | Description                       |
| ------------------------------------------------------------------------------------ | --------------------------------- |
| `client.address.autocomplete(q=..., state=..., limit=..., debug=...)`                | Real-time typeahead suggestions.  |
| `client.address.validate(q=..., debug=...)`                                          | Verify a full address string.     |
| `client.address.enrich(id=..., debug=...)`                                           | Full record by G-NAF ID.          |
| `client.address.reverse_geocode(lat=..., lon=..., radius=..., limit=..., debug=...)` | Coordinates to nearest addresses. |
| `client.address.lookup.by_postcode(postcode=..., limit=..., debug=...)`              | Postcode to localities.           |
| `client.address.lookup.by_suburb(suburb=..., state=..., limit=..., debug=...)`       | Suburb to postcodes.              |