Ideal Postcodes Python SDK

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.

pip install ideal-postcodes

lookup.pypython

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: every address at a UK postcode
• UPRN lookup: the address for a Unique Property Reference Number
• Address cleanse: match a messy address to the right record
• Email validation and phone validation
• API keys and licensees: balances, limits, usage and sublicensing

The rest, including address autocomplete, place search and saved configs, is on the endpoint pages, 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.
• llms.txt. An index of every page on this site.
• OpenAPI spec. The contract the SDK is generated from.