Python

Official Python client for Addresso UK address lookups. Zero dependencies, typed frozen dataclasses, and full IDE autocomplete.

PyPI — addresso

Installation

Requires Python 3.9 or later. No external dependencies.

bash

pip install addresso

Usage

Create a Client with your API key. All methods return typed frozen dataclasses.

python

from addresso import Client

client = Client("ak_your_api_key")

# Postcode lookup
result = client.lookup_postcode("SW1A 1AA")

for address in result.addresses:
    print(f"{address.building_number} {address.street}, {address.town}")

# Address search
result = client.search_addresses(q="10 Downing Street")

# Account info
account = client.account()
print(f"Credits: {account.credits_balance}")

Constructor

api_keystrrequired

Your Addresso API key (begins with ak_).

base_urlstr

Override the API base URL. Defaults to https://addresso.co.uk.

Postcode lookup

Look up all addresses at a UK postcode. Returns a PostcodeLookupResult.

python

result = client.lookup_postcode("SW1A 1AA")

result.postcode           # "SW1A 1AA"
len(result.addresses)     # number of addresses
result.credits_remaining  # credits left

for address in result.addresses:
    print(address.building_name)
    print(address.street)
    print(address.town)

Address search

Search using keyword arguments. Returns an AddressSearchResult.

python

# Free-text search
result = client.search_addresses(q="10 Downing Street")

# Structured search
result = client.search_addresses(
    town="London",
    street="Downing Street",
    building_number="10",
    limit=5,
)

result.count              # total matches
result.credits_remaining  # credits left

Search parameters

qstr

Free-text query across all fields.

postcodestr

Filter by postcode.

townstr

Filter by town.

streetstr

Filter by street name.

building_namestr

Filter by building name.

building_numberstr

Filter by building number.

organisationstr

Filter by organisation.

limitint

Max results to return (default 50).

Account

Check your account status and remaining credits.

python

account = client.account()

account.company_name      # your company name
account.credits_balance   # credits remaining
account.earliest_expiry   # earliest credit expiry date (or None)

Data classes

All responses are frozen dataclasses. The Address class contains these fields:

postcodestr

Full postcode.

townstr

Post town.

localitystr

Locality name.

sub_localitystr

Sub-locality.

streetstr

Primary street name.

secondary_streetstr

Secondary street.

building_numberstr

Building number.

building_namestr

Building name.

sub_buildingstr

Sub-building (flat, unit, etc.).

po_boxstr

PO box number.

departmentstr

Department name.

organisationstr

Organisation name.

udprnint

Unique Delivery Point Reference Number.

postcode_typestr

Postcode type (S or L).

delivery_point_suffixstr

Royal Mail delivery point suffix.

latitudefloat | None

WGS84 latitude, or None.

longitudefloat | None

WGS84 longitude, or None.

Error handling

All API errors raise AddressoException with a status_code attribute.

python

from addresso import AddressoException

try:
    result = client.lookup_postcode("INVALID")
except AddressoException as e:
    print(e)              # "Invalid postcode"
    print(e.status_code)  # 400