← All docs

PHP

Official PHP client for integrating Addresso UK address lookups into any PHP application. Zero dependencies, typed data classes, and full IDE autocomplete.

Packagist — addresso/addresso-php

Installation

Requires PHP 8.1 or later with the curl and json extensions (enabled by default on most installs).

bash
composer require addresso/addresso-php

Usage

Create a Client with your API key. All methods return typed readonly objects with full IDE autocomplete.

php
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 . "\n";
}

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

// Account info
$account = $client->account();
echo "Credits: " . $account->creditsBalance;

Constructor

apiKeystringrequired

Your Addresso API key (begins with ak_).

baseUrlstring

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

Postcode lookup

Look up all addresses at a UK postcode. Returns a PostcodeLookupResult with an array of typed Address objects.

php
$result = $client->lookupPostcode('SW1A 1AA');

echo $result->postcode;          // "SW1A 1AA"
echo count($result->addresses);  // number of addresses
echo $result->creditsRemaining;  // credits left

foreach ($result->addresses as $address) {
    echo $address->buildingName;
    echo $address->street;
    echo $address->town;
}

Address search

Search for addresses using free text or structured fields. Returns an AddressSearchResult.

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

// Structured search
$result = $client->searchAddresses([
    'town' => 'London',
    'street' => 'Downing Street',
    'building_number' => '10',
    'limit' => 5,
]);

echo $result->count;             // total matches
echo $result->creditsRemaining;  // credits left

Search parameters

qstring

Free-text query across all fields.

postcodestring

Filter by postcode.

townstring

Filter by town.

streetstring

Filter by street name.

building_namestring

Filter by building name.

building_numberstring

Filter by building number.

organisationstring

Filter by organisation.

limitint

Max results to return (default 50).

Account

Check your account status and remaining credits.

php
$account = $client->account();

echo $account->companyName;     // your company name
echo $account->creditsBalance;  // credits remaining
echo $account->earliestExpiry;  // earliest credit expiry date (or null)

Data classes

All API responses are mapped to typed readonly objects. The Address class contains these properties:

postcodestring

Full postcode.

townstring

Post town.

localitystring

Locality name.

subLocalitystring

Sub-locality.

streetstring

Primary street name.

secondaryStreetstring

Secondary street.

buildingNumberstring

Building number.

buildingNamestring

Building name.

subBuildingstring

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

poBoxstring

PO box number.

departmentstring

Department name.

organisationstring

Organisation name.

udprnint

Unique Delivery Point Reference Number.

postcodeTypestring

Postcode type (S or L).

deliveryPointSuffixstring

Royal Mail delivery point suffix.

latitude?float

WGS84 latitude, or null.

longitude?float

WGS84 longitude, or null.

Error handling

All API errors throw AddressoException which extends RuntimeException. Use getStatusCode() to inspect the HTTP status.

php
use Addresso\AddressoException;

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