postcodes
Lookup Postcode
Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.
Each request looks up one postcode. To extract the addresses for several postcodes, send one request per postcode.
Use it to power postcode driven address searches, like Postcode Lookup.
Postcode lookup covers the United Kingdom, the Republic of Ireland, the Netherlands and Singapore. The API detects the format of the postcode you submit. UK and Irish postcodes are searched by default. For a Dutch or Singapore postcode, set context to NLD or SGP, or to GLOBAL to accept any supported format.
UK postcodes need PAF, Multiple Residence, Not Yet Built, PAF Alias, PAF Welsh, AddressBase or AddressBase Premium on your key. Eircodes need ECAD or ECAF. Dutch postcodes need Kadaster. Singapore postcodes need HERE Asia Pacific. Without a matching licence the request is rejected.
An unfound postcode costs no lookup. A postcode that returns addresses costs one.
Postcode Not Found
Invalid postcodes do not affect your lookup balance. The API returns a 404 response with this body:
{
"code": 4040,
"message": "Postcode not found",
"suggestions": ["SW1A 0AA"]
}
Suggestions
If a postcode cannot be found, the API returns up to 5 of the closest matching postcodes. It corrects common errors first (e.g. mixing up O and 0 or I and 1).
If the suggestion list is small (fewer than 3), the correct postcode is likely to be among them. Notify the user or trigger new searches immediately.
The suggestion list is empty if the postcode has deviated too far from a valid postcode format.
Multiple Residence
A small number of postcodes return more than 100 premises. The API returns 100 addresses per page, so use page to paginate the result set.
Endpoint
GET /postcodes/{postcode}
See the API reference for this endpoint.
Import
from ideal_postcodes import IdealPostcodes
Call postcodes on the IdealPostcodes client. Path parameters are positional; query and body parameters are keyword-only.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
postcode | str | yes | Postcode to retrieve |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | str | no | Restrict Result Fields Comma separated whitelist of address elements to return. E.g. filter=line_1,line_2,line_3 returns only the line_1, line_2 and line_3 address elements in your response. |
page | int | no | Page 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises). |
tags | str | no | Tags A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". |
dataset | list[types.Dataset] | no | Filter by Dataset Comma-separated list of datasets to search within. Filters results to only include addresses from the specified datasets. Useful for keys with multiple overlapping datasets enabled (e.g. paf and abp). |
context | str | no | Context Limits search results, typically within a country. |
Response Type
from ideal_postcodes.types import PostcodesResult
With filter, returns dictionaries of the requested fields instead of models.
Errors
Unsuccessful HTTP responses raise APIError or a subclass, with the HTTP status and the API error code and message. Connection failures and timeouts raise TransportError. Unexpected responses raise ProtocolError. All derive from ClientError. See error handling.
Example
from ideal_postcodes import IdealPostcodes
with IdealPostcodes("ak_test") as client:
addresses = client.postcodes("BR8 7RE")