Postcode Lookup API

Authentication

All API requests require a Bearer token in the Authorization header.

How to get your token:

1. Register an account at http://portal.goaddress.io/register
2. Upon successful registration, a unique API token is automatically generated and associated with your account.
3. You can view or regenerate your token in your account dashboard after logging in.

Use the token like this:

Authorization: Bearer {your-api-token}

1. Find Addresses by Partial Postcode (e.g., /w148ns)

Returns a list of addresses matching the partial postcode.

Request

GET https://portal.goaddress.io/api/address/{partial-postcode}

Example

GET https://portal.goaddress.io/api/address/w148ns

Response

{
  "postcode": "nw43ta",
  "total": 31,
  "addresses": [
    "28 Algernon Road",
    "28A, Algernon Road",
    "29 Algernon Road",
    // ... (truncated for brevity)
    "Interface Industries Ltd, 40A, Algernon Road"
  ],
  "credits_remaining": 43
}

2. Search Addresses by Postcode

Returns structured address results for the given postcode query.

Request

GET https://portal.goaddress.io/api/address/search?q={postcode}

Example

GET https://portal.goaddress.io/api/address/search?q=nw43ta

Response

{
  "query": "nw43ta",
  "count": 31,
  "results": [
    {
      "address": "28 Algernon Road",
      "postcode": "NW43TA",
      "label": "28 Algernon Road, NW43TA"
    },
    // ... (other results)
    {
      "address": "Interface Industries Ltd, 40A, Algernon Road",
      "postcode": "NW43TA",
      "label": "Interface Industries Ltd, 40A, Algernon Road, NW43TA"
    }
  ]
}

Code Examples

Here are examples of how to call the postcode lookup endpoint in various languages (using the search endpoint as example).

cURL

curl -X GET "https://portal.goaddress.io/api/address/search?q=nw43ta" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

JavaScript (Fetch)

fetch('https://portal.goaddress.io/api/address/search?q=nw43ta', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Node.js (Axios)

const axios = require('axios');

axios.get('https://portal.goaddress.io/api/address/search?q=nw43ta', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

PHP (cURL)

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://portal.goaddress.io/api/address/search?q=nw43ta");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_TOKEN"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

.NET (C# - HttpClient)

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");

var response = await client.GetAsync("https://portal.goaddress.io/api/address/search?q=nw43ta");
var content = await response.Content.ReadAsStringAsync();

Console.WriteLine(content);