REST API

Call the Addresso API directly from any language or platform. Authenticate with a Bearer token, search addresses, and pay only for what you use.

3 endpoints

Postcode, Address & Account

1 credit

Per API call

50 max

Results per request

Authentication

Every request requires a valid API key passed as a Bearer token. Create keys from your API Keys dashboard. Keys begin with ak_.

Header

Authorization: Bearer ak_your_api_key_here

Postcode Lookup

Retrieve every delivery point at a UK postcode. Returns the full PAF record for each address.

GET/api/postcodes/:postcode

Path parameters

postcodestringrequired

UK postcode. Spaces are optional — both SW1A1AA and SW1A 1AA work.

Example

bash

curl -H "Authorization: Bearer ak_your_key" \
  "https://addresso.co.uk/api/postcodes/SW1A1AA"

Address Search

Flexible address search using free-text queries, structured filters, or both combined. At least one search parameter is required.

GET/api/addresses

Query parameters

qstring

Free-text search. Automatically detects postcodes. Otherwise each word is matched across all address fields.

postcodestring

Filter by exact postcode (normalised automatically).

townstring

Filter by exact town (case-insensitive).

streetstring

Filter by street name (partial match).

building_namestring

Filter by building name (partial match).

building_numberstring

Filter by exact building number.

organisationstring

Filter by organisation name (partial match).

limitnumber

Maximum results to return. Default and maximum is 50.

Free-text search

bash

curl -H "Authorization: Bearer ak_your_key" \
  "https://addresso.co.uk/api/addresses?q=10+Downing+Street"

Structured filters

bash

curl -H "Authorization: Bearer ak_your_key" \
  "https://addresso.co.uk/api/addresses?town=London&street=Downing"

Combined search

bash

curl -H "Authorization: Bearer ak_your_key" \
  "https://addresso.co.uk/api/addresses?q=Westminster&postcode=SW1A+1AA"

Account Status

Check your account's current credit balance and organisation details. This endpoint does not consume any credits.

GET/api/account

Example

bash

curl -H "Authorization: Bearer ak_your_key" \
  "https://addresso.co.uk/api/account"

Response fields

company.namestring

Your organisation name.

credits.balancenumber

Total credits available across all active batches.

credits.earliest_expirystring|null

ISO 8601 timestamp of the earliest credit batch expiry, or null if no credits remain.

Response Codes

200

Request completed successfully. The response body contains the matching addresses.

400

Bad Request

Missing or invalid parameters. For address search, at least one search parameter is required.

401

Unauthorized

Missing, invalid, or revoked API key. Check your Authorization header.

402

Payment Required

Insufficient credits. Top up on the Billing page.

Address Fields

Every address object in the response contains the following fields.

Field	Description
`postcode`	UK postcode (space-separated)
`town`	Town
`street`	Street name
`secondary_street`	Secondary street name
`building_number`	Building number
`building_name`	Building name
`sub_building`	Flat, unit, or sub-building identifier
`organisation`	Organisation at this address
`department`	Department within the organisation
`locality`	Village or neighbourhood
`sub_locality`	Sub-locality
`po_box`	PO Box number
`udprn`	Unique Delivery Point Reference Number
`postcode_type`	S (small user) or L (large user)
`delivery_point_suffix`	Royal Mail delivery point suffix
`formatted_address`	Comma-separated one-line summary of the address
`latitude`	Latitude of the postcode centroid (ONS)
`longitude`	Longitude of the postcode centroid (ONS)