Postcode Lookup API

Retrieve full address lists for a UK postcode or search addresses by postcode.

1. Find Addresses by Partial Postcode

Returns a list of addresses matching the provided partial or full postcode. This endpoint is useful for quickly retrieving all addresses within a postcode.

Request

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

Example


GET https://portal.goaddress.io/api/address/HA3 7HZ

Response


{
  "postcode": "HA3 7HZ",
  "total": 16,
  "addresses": [
    "100 Warham Road",
    "102 Warham Road",
    "104 Warham Road",
    "106 Warham Road"
    // ... truncated for brevity
  ],
  "new_address_res": [
    {
      "raw_address": "100 Warham Road",
      "house_no": "100",
      "street": "100 Warham Road",
      "road": "100 Warham Road",
      "building_name": null,
      "postcode": "HA3 7HZ",
      "post_town": "London",
      "city": "London",
      "town": "Harrow",
      "county": "Metropolitan Police",
      "district": "Harrow",
      "region": "London",
      "country": "England"
    }
    // ... truncated for brevity
  ],
  "address_info": {
    "postcode": "HA3 7HZ",
    "post_town": "London"
    // ... truncated for brevity
  },
  "extra_info": {
    "postcode": "HA3 7HZ",
    "quality": 1,
    "eastings": 515678,
    "northings": 190321
    // ... truncated for brevity
  },
  "usage_today": 1,
  "daily_limit": 15000,
  "remaining_today": 14999
}

Notes

The postcode can be partial or complete.
Addresses are returned as raw strings in addresses.
new_address_res provides structured address fields for easier integration.
Use extra_info and address_info for detailed postcode metadata.

2. Search Addresses

Returns structured address results based on a postcode or partial address query. Supports optional postcode filtering for more accurate results.

Request


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

Examples


GET https://portal.goaddress.io/api/address/search?q=HA3 7HZ
GET https://portal.goaddress.io/api/address/search?q=100 Warham&postcode=HA3 7HZ
GET https://portal.goaddress.io/api/address/search?q=100 Warham
GET https://portal.goaddress.io/api/address/search?q=100 Warham&postcode=HA3 7HZ
GET https://portal.goaddress.io/api/address/search?q=100A&postcode=HA3 7HZ
GET https://portal.goaddress.io/api/address/search?q=Warham&postcode=HA3 7HZ

Response

                
{
  "query": "100",
  "count": 1,
  "results": [
      {
          "address": "100 Warham Road",
          "postcode": "HA37HZ",
          "label": "100 Warham Road, HA37HZ"
      }
  ],
  "new_address_res": [
      {
          "raw_address": "100 Warham Road",
          "flat": null,
          "house_no": "100",
          "street": "Warham Road",
          "road": "Warham Road",
          "building_name": null,
          "postcode": "HA37HZ",
          "post_town": "London",
          "city": "London",
          "town": "Harrow",
          "county": "Metropolitan Police",
          "district": "Harrow",
          "region": "London",
          "country": "England"
      }
  ],
  "extra_info": null,
  "address_info": null,
  "usage_today": 2,
  "daily_limit": 15000,
  "remaining_today": 14998
}

Notes

postcode parameter is optional.
If postcode is provided, results are filtered to that postcode only.
new_address_res provides structured address fields for easier integration.
All original address strings remain available via raw_address.

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);