README

Official PHP client for the Addresso UK address lookup API.

• PHP 8.1+
• Zero dependencies (uses built-in cURL)
• Typed data classes with full IDE autocomplete

Installation

composer require addresso/addresso-php

Quick start

use Addresso\Client;

$client = new Client('ak_your_api_key');

// Postcode lookup
$result = $client->lookupPostcode('SW1A 1AA');

foreach ($result->addresses as $address) {
    echo "{$address->buildingNumber} {$address->street}, {$address->town}\n";
}

// Address search
$result = $client->searchAddresses(['q' => '10 Downing Street']);

echo "Found {$result->count} addresses\n";

// Account info
$account = $client->account();

echo "Credits remaining: {$account->creditsBalance}\n";

API

Client

$client = new Client(string $apiKey, string $baseUrl = 'https://addresso.co.uk');

lookupPostcode(string $postcode): PostcodeLookupResult

Look up all addresses at a UK postcode.

searchAddresses(array $params): AddressSearchResult

Search for addresses by free text or structured fields. Supported params: q, postcode, town, street, building_name, building_number, organisation, limit.

account(): AccountResult

Get your account status and remaining credits.

Data classes

All results return typed readonly objects:

• Address — postcode, town, locality, subLocality, street, secondaryStreet, buildingNumber, buildingName, subBuilding, poBox, department, organisation, udprn, postcodeType, deliveryPointSuffix, latitude, longitude
• PostcodeLookupResult — postcode, addresses (Address[]), creditsRemaining
• AddressSearchResult — query, addresses (Address[]), count, creditsRemaining
• AccountResult — companyName, creditsBalance, earliestExpiry

Error handling

All API errors throw AddressoException which extends RuntimeException:

use Addresso\AddressoException;

try {
    $result = $client->lookupPostcode('INVALID');
} catch (AddressoException $e) {
    echo $e->getMessage();       // "Invalid postcode"
    echo $e->getStatusCode();    // 400
}

License

MIT