# Ideal Postcodes Python SDK

[`ideal-postcodes`](https://pypi.org/project/ideal-postcodes/) is the Python client for the Ideal Postcodes API. It has one typed method per API operation and returns each response as a Pydantic model. It needs Python 3.12 or later.

```bash
pip install ideal-postcodes
```

lookup.pypython

```python
from ideal_postcodes import IdealPostcodes

with IdealPostcodes("ak_test") as client:
    for address in client.postcodes("BR8 7RE"):
        print(address.line_1, address.post_town, address.uprn)
```

`ak_test` is a shared test key limited to 5 requests a day. A new account comes with a free test balance.

## Capabilities

Every operation in the API has a method. The ones most integrations need have a guide:

* [Postcode lookup](/docs/sdks/python/postcode-lookup.md): every address at a UK postcode
* [UPRN lookup](/docs/sdks/python/uprn-lookup.md): the address for a Unique Property Reference Number
* [Address cleanse](/docs/sdks/python/address-cleanse.md): match a messy address to the right record
* [Email validation](/docs/sdks/python/email-validation.md) and [phone validation](/docs/sdks/python/phone-validation.md)
* [API keys](/docs/sdks/python/keys.md) and [licensees](/docs/sdks/python/licensees.md): balances, limits, usage and sublicensing

The rest, including address autocomplete, place search and saved configs, is on the [endpoint pages](/docs/sdks/python/endpoints/.md), one per method.

## SDK vs direct API calls

* Each method takes the API's parameters as typed arguments, so Pyright and mypy catch a misspelt argument before you run it
* The SDK checks each response against the OpenAPI spec and raises `ProtocolError` if it does not match
* It never retries on its own, so a billable lookup repeats only when your code repeats it
* It depends on HTTPX and Pydantic, nothing else

## Coding agents

* **Agent skill.** `npx skills add ideal-postcodes/skills` installs the `ideal-postcodes-python-sdk` skill, built from these pages.
* **Markdown.** Add `.md` to any page URL, such as [`/docs/sdks/python/postcode-lookup.md`](/docs/sdks/python/postcode-lookup.md).
* **[llms.txt](https://docs.ideal-postcodes.co.uk/llms.txt).** An index of every page on this site.
* **[OpenAPI spec](https://openapi.ideal-postcodes.co.uk/openapi.json).** The contract the SDK is generated from.