Python SDK

ideal-postcodes is our Python SDK for the Ideal Postcodes API. It has one typed method for every API operation, returns each response as a Pydantic model and runs on Python 3.12 or later.

Details

• Every operation: Postcode lookup, address search and autocomplete, UPRN lookup, address cleanse, email and phone validation, plus key, licensee and configuration management
• Typed arguments: Each method takes the API's parameters as keyword arguments, so Pyright and mypy catch a misspelt argument before the code runs
• Inputs checked before sending: Ranges, lengths and allowed values are validated against the OpenAPI spec before a request leaves your machine
• Responses checked on arrival: Each response is validated against the spec. A mismatch raises ProtocolError, which still carries the raw result
• Typed errors: Failed requests raise APIError subclasses such as NotFoundError and RateLimitError, with the HTTP status, API error code and message
• No silent retries: The SDK never retries on its own, so a billable lookup repeats only when your code repeats it
• Two dependencies: HTTPX and Pydantic, nothing else
• Agent skill: npx skills add ideal-postcodes/skills gives coding agents the ideal-postcodes-python-sdk skill

Install with pip install ideal-postcodes, then start with the Python SDK documentation.