UK addresses use an alphanumeric postal code with a significant space, place the house number before the street name, and often include building names. The hierarchical address system makes autocomplete particularly valuable — a single street can contain dozens of individual premises.
{
"countryCode": "GB",
"postalCode": "SW1A 2AA",
"addressLines": ["10 Downing Street"],
"locality": "London"
}| Field | Required | Description |
|---|---|---|
countryCode | Yes | Always "GB" |
postalCode | Yes | Alphanumeric with space |
addressLines | Yes (for shipment) | Index 0: number and street name |
locality | Yes (for shipment) | Post town |
administrativeArea | No | County — not required for delivery |
subLocality | No | London district or neighborhood, e.g., "Westminster" |
- Format: Alphanumeric, with a space separating the outward and inward parts
- Pattern: Various formats (
A9 9AA,A99 9AA,A9A 9AA,AA9 9AA,AA99 9AA,AA9A 9AA) - Examples:
"SW1A 2AA","EC2R 8AH","M1 1AE" - Sanitization: The API preserves spaces. Letters are uppercased.
The space in UK postal codes is significant. "SW1A 2AA" and "SW1A2AA" may be handled differently by carriers. Always include the space.
The house number comes before the street name. Building names, when present, go on a preceding line.
| Scenario | addressLines value |
|---|---|
| Standard | ["10 Downing Street"] |
| With building name | ["Buckingham Palace", "The Mall"] |
| With flat number | ["Flat 3", "10 Buckingham Street"] |
- Building names are common in the UK and may replace a house number entirely
- The autocomplete endpoint returns building names in the correct position
The locality field is the post town, which may differ from the colloquial city name.
- Example:
"London","Manchester","Edinburgh" - For London addresses,
subLocalitycan capture the specific district
UK addresses benefit significantly from autocomplete due to:
- Multi-premise buildings: A single building may contain many flats, each a separate address. The expand/resolve pattern handles this naturally.
- Building names: Many UK addresses use building names instead of or in addition to house numbers, making free-text entry error-prone.
- PAF data: The UK has a comprehensive Postcode Address File. The autocomplete endpoint with
focus=postalCodeenables postcode-first lookups common in UK checkouts.
| Mistake | Problem | Fix |
|---|---|---|
"postalCode": "sw1a 2aa" | Lowercase postal code | Accepted — the API uppercases automatically |
"postalCode": "SW1A2AA" | Missing space | Include the space: "SW1A 2AA" |
"addressLines": ["Downing Street 10"] | Street before number | UK uses number-first: ["10 Downing Street"] |
| Missing building name | Building-only addresses fail delivery | Use autocomplete to capture building names |