List the addresses at a postcode

Answers the addresses at one postcode, in the partner's own order, for callers that want a "find my address" picker under a postcode field.

This is the one address answer no open dataset carries: every full address list is derived from a postal operator's own address file, and serving it needs a licence. Until a partner is configured for the country, the endpoint answers 501 ADDRESS_LIST_UNAVAILABLE and charges nothing, rather than returning an empty list that would read as "there are no addresses here". Nothing else in the address API depends on it.

country is an ISO 3166-1 alpha-2 code and defaults to GB. The postcode is passed in the path, with or without its space (NW1 6XE and NW16XE are the same postcode). At most 100 addresses are returned for one postcode; count is how many the answer carries.

curl https://spaw.co/api/v1/address/postcode/NW1 6XE \
  -H "Authorization: Bearer sk_live_…"

const response = await fetch('https://spaw.co/api/v1/address/postcode/NW1 6XE', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_…',
  },
});
const result = await response.json();

import requests

response = requests.get(
    'https://spaw.co/api/v1/address/postcode/NW1 6XE',
    headers={'Authorization': 'Bearer sk_live_…'},
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/address/postcode/NW1 6XE');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…'],
]);
$result = json_decode(curl_exec($ch), true);

{
    "success": true,
    "data": {
        "postcode": "NW1 6XE",
        "country": "GB",
        "available": true,
        "addresses": [
            {
                "address_line1": "221B Baker Street",
                "address_line2": null,
                "organization": null,
                "street": "Baker Street",
                "house_number": "221B",
                "unit": null,
                "locality": "London",
                "administrative_area": null,
                "postal_code": "NW1 6XE",
                "country": "GB",
                "identifier": "10023456789"
            }
        ],
        "count": 1
    },
    "meta": {
        "credits_used": 2,
        "credits_remaining": 8,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "ADDRESS_LIST_UNAVAILABLE",
        "message": "Listing the addresses at a postcode needs a licensed address-list partner, and none is configured for GB.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}