API Documentation

Integrate UK address lookup into your application in minutes.

Authentication

Address lookup requests are authenticated using an API key passed as a query parameter. You can create and manage API keys from your Dashboard.

GET /api/v1/autocomplete?query=baker+street&api_key=gua_your_key_here

Endpoints

GET/api/v1/autocomplete

Search for UK addresses by postcode or address text. Requires a valid API key and active subscription.

Query Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Postcode or address text (min 3 characters)
`api_key`	string	Yes	Your API key

Example Request

curl "https://getukaddress.com/api/v1/autocomplete?query=SW1A+1AA&api_key=gua_your_key"

Success Response 200

{
  "requestId": "0HN8A1B2C3D4E:00000001",
  "results": [
    {
      "organisation": "",
      "addressLine1": "Buckingham Palace",
      "addressLine2": "",
      "town": "London",
      "postcode": "SW1A 1AA",
      "summaryLine": "Buckingham Palace, London, SW1A 1AA"
    }
  ]
}

Response Fields

Field	Type	Description
`requestId`	string	Unique identifier for the request
`results`	array	List of matching addresses
`results[].organisation`	string	Organisation name (if applicable)
`results[].addressLine1`	string	Primary address line
`results[].addressLine2`	string	Secondary address line
`results[].town`	string	Town or city
`results[].postcode`	string	UK postcode
`results[].summaryLine`	string	Full address as a single comma-separated string

Rate Limiting

Each subscription plan has a daily request limit. Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Your daily request limit
`X-RateLimit-Remaining`	Requests remaining today
`X-RateLimit-Reset`	UTC timestamp when the limit resets (midnight UTC)

Error Handling

All errors are returned as RFC 9457 Problem Details JSON with Content-Type: application/problem+json.

Error Response Format

{
  "type": "https://getukaddress.com/errors/rate-limit-exceeded",
  "title": "RATE_LIMIT_EXCEEDED",
  "status": 429,
  "detail": "Daily limit of 500 requests exceeded. Resets at midnight UTC.",
  "instance": "/api/v1/autocomplete",
  "requestId": "0HN8A1B2C3D4E:00000001",
  "code": "RATE_LIMIT_EXCEEDED"
}

Error Codes

HTTP Status	Code	Description
`400`	`INVALID_REQUEST`	Query is missing or less than 3 characters
`401`	`INVALID_API_KEY`	API key is missing, invalid, or revoked
`403`	`EMAIL_NOT_VERIFIED`	Account email has not been verified
`403`	`ACCOUNT_SUSPENDED`	Account has been suspended
`403`	`SUBSCRIPTION_EXPIRED`	No active subscription found
`429`	`RATE_LIMIT_EXCEEDED`	Daily request limit exceeded
`500`	`INTERNAL_ERROR`	Unexpected server error