REST API Bearer token auth

GoAddress API Documentation

Use the GoAddress API to search UK addresses by postcode or by free-text keyword. Responses include simple labels, structured address fields, display lines, and daily usage counters.

Postcode lookup Keyword search

Authentication

All requests require an API token in the Authorization header. Replace <token> with your live API token.

Authorization header

Accept: application/json
Authorization: Bearer <token>

Security

Keep your token server-side. Do not expose it in public frontend JavaScript.

Base URL

All examples use the production portal base URL.

GEThttps://portal.goaddress.io/api

Search Address By Postcode

Use this endpoint when you have a postcode and want every address linked to it.

GET/address/{postcode}

Path parameters

Name	Type	Description
`postcode` required	string	UK postcode without or with spaces, for example `N33RP` or `N3 3RP`.

cURL request

cURL

curl --location 'https://portal.goaddress.io/api/address/N33RP' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

Search Address By Keyword

Use keyword search for postcode text, street names, house numbers, or a combination of query and postcode.

GET/address/search?q={query}

GET/address/search?q={query}&postcode={postcode}

Query parameters

Name	Type	Description
`q` required	string	Search text. This can be a postcode, address keyword, house number, or street name.
`postcode` optional	string	Limits the keyword search to a specific postcode.

cURL request

cURL

curl --location 'https://portal.goaddress.io/api/address/search?q=AB422UB' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

Examples

GET examples

GET https://portal.goaddress.io/api/address/search?q=AB422UB
GET https://portal.goaddress.io/api/address/search?q=Viking Way&postcode=AB422UB
GET https://portal.goaddress.io/api/address/search?q=Viking Way
GET https://portal.goaddress.io/api/address/search?q=9&postcode=AB422UB

Response Example

The API returns the original query, a result count, display-friendly results, structured address objects, address lines, and usage counters.

200 OK - application/json

{
  "query": "AB422UB",
  "count": 32,
  "results": [
    {
      "addressid": "eb4e61a6",
      "address": "1 Viking Way",
      "postcode": "AB422UB",
      "label": "1 Viking Way, AB422UB"
    },
    {
      "addressid": "2864053d",
      "address": "10 Viking Way",
      "postcode": "AB422UB",
      "label": "10 Viking Way, AB422UB"
    },
    {
      "addressid": "014ee7ae",
      "address": "9 Viking Way",
      "postcode": "AB422UB",
      "label": "9 Viking Way, AB422UB"
    }
  ],
  "new_address_res": [
    {
      "flat": null,
      "houseNo": "1",
      "building_name": "",
      "organisation": "",
      "street": "Viking Way",
      "addressid": "eb4e61a6",
      "raw_address": "1 Viking Way",
      "postcode": "AB422UB",
      "post_town": "Peterhead",
      "city": "Aberdeenshire",
      "town": "Peterhead",
      "county": "Aberdeenshire",
      "district": "Aberdeenshire",
      "region": "",
      "country": "Scotland"
    },
    {
      "flat": null,
      "houseNo": "10",
      "building_name": "",
      "organisation": "",
      "street": "Viking Way",
      "addressid": "2864053d",
      "raw_address": "10 Viking Way",
      "postcode": "AB422UB",
      "post_town": "Peterhead",
      "city": "Aberdeenshire",
      "town": "Peterhead",
      "county": "Aberdeenshire",
      "district": "Aberdeenshire",
      "region": "",
      "country": "Scotland"
    }
  ],
  "new_address_res2": [
    {
      "addressid": "eb4e61a6",
      "line_1": "1 Viking Way",
      "line_2": "Aberdeenshire",
      "line_3": "AB422UB",
      "line_4": "Scotland"
    },
    {
      "addressid": "2864053d",
      "line_1": "10 Viking Way",
      "line_2": "Aberdeenshire",
      "line_3": "AB422UB",
      "line_4": "Scotland"
    }
  ],
  "extra_info": null,
  "address_info": {
      "postcode": "AB422UB",
      "post_town": "Peterhead",
      "city": "Aberdeenshire",
      "town": "Hatton",
      "county": "Aberdeenshire",
      "district": "Aberdeenshire",
      "region": "",
      "country": "Scotland"
  },
  "usage_today": 4,
  "daily_limit": 200,
  "remaining_today": 196
}

Usage Fields

Field	Description
`usage_today`	Number of lookups already used today.
`daily_limit`	Your plan's daily lookup limit.
`remaining_today`	Lookups still available today.

Need help?

Email support@goaddress.io if you need help integrating the API.