Skip to content
Street GB

Docs

Look up a postcode.

One GET request. You receive the street, place and coordinates. You collect the house number yourself. Replace the example host with the base URL from your welcome email.

Overview

Authenticate with a bearer key. The path is the postcode, with or without a space. The body never includes a house number: that field is the fixed string collect from user.

  • Coverage is England, Scotland and Wales.
  • BT postcodes return not_covered.
  • A successful response is not address validation.
  • Typical latency on the live API is 25–45 ms.

Not a house list, and not address validation.

The customer types the house number. Do not treat a 200 response as proof the building exists.

Endpoint

GET /postcode/{postcode}

Send Authorization: Bearer st_test_your_key. Both NW10 5HG and NW105HG are accepted. URL-encode the space if you include one.

curl

curl https://api.streetgb.co.uk/postcode/NW105HG \
  -H "Authorization: Bearer st_test_your_key" \
  -H "Accept: application/json"

Authentication

Keys look like st_test_your_key. Prefer calling from your server so the key is not visible in the browser. The widget can hold a publishable key if you accept that trade-off.

Response

street is the candidate with the largest share. When multi_street is true, show street_candidates and let the customer confirm. share is a fraction of properties on the postcode. confidence is high at 0.5 and above, medium from 0.2, otherwise low.

One street: NW10 5HG

200 application/json

{
  "postcode": "NW10 5HG",
  "status": "ok",
  "lat": 51.535941,
  "lng": -0.222445,
  "street": "Whitmore Gardens",
  "multi_street": false,
  "street_candidates": [
    {
      "name": "Whitmore Gardens",
      "share": 1,
      "confidence": "high"
    }
  ],
  "locality": null,
  "town": "London",
  "county": "Greater London",
  "admin": {
    "council": "Brent",
    "ward": "Queens Park",
    "constituency": "Queen's Park and Maida Vale",
    "region": "London",
    "country": "England"
  },
  "uprn_count": 29,
  "house_number": "collect from user",
  "sources": [
    "ONS UPRN Directory",
    "ONS Postcode Directory",
    "OS Code-Point Open",
    "OS Open Roads",
    "OS Open Names"
  ]
}

Several streets: NW3 2BB

Parkhill Road, Haverstock Hill and England’s Lane share this postcode in the sample. An “Other” choice is a widget behaviour, not an API candidate.

200 application/json

{
  "postcode": "NW3 2BB",
  "status": "ok",
  "lat": 51.54767,
  "lng": -0.159579,
  "street": "Parkhill Road",
  "multi_street": true,
  "street_candidates": [
    {
      "name": "Parkhill Road",
      "share": 0.54,
      "confidence": "high"
    },
    {
      "name": "Haverstock Hill",
      "share": 0.24,
      "confidence": "medium"
    },
    {
      "name": "England's Lane",
      "share": 0.22,
      "confidence": "medium"
    }
  ],
  "locality": null,
  "town": "London",
  "county": "Greater London",
  "admin": {
    "council": "Camden",
    "ward": "Haverstock",
    "constituency": "Holborn and St Pancras",
    "region": "London",
    "country": "England"
  },
  "uprn_count": 37,
  "house_number": "collect from user",
  "sources": [
    "ONS UPRN Directory",
    "ONS Postcode Directory",
    "OS Code-Point Open",
    "OS Open Roads",
    "OS Open Names"
  ]
}

Errors

HTTPstatusWhen
200okPostcode found in Great Britain
400invalidNot a UK postcode
404not_foundWell-formed GB postcode with no open-data record
422not_coveredNorthern Ireland (BT)
401unauthorizedMissing or wrong key
429quota_exceededFree quota used up, or the rate limit

422 not_covered

{
  "postcode": "BT1 1AA",
  "status": "not_covered",
  "message": "Northern Ireland postcodes are not covered. This API is Great Britain only."
}

400 invalid

{
  "postcode": null,
  "status": "invalid",
  "message": "That is not a UK postcode."
}

404 not_found

{
  "postcode": "ZZ99 9ZZ",
  "status": "not_found",
  "message": "No Great Britain postcode matched."
}

Drop-in widget

The script renders a postcode field, the street (or the ranked picker), and a house-number box. houseNumber in the callback is what the customer typed. The widget does not send that value to the API.

Place it on a page you control: a basket, a lead form, or a WooCommerce checkout template. Shopify’s hosted checkout does not allow arbitrary scripts on every plan. There is no hosted app to install.

HTML

<div id="address-lookup"></div>
<script src="https://cdn.streetgb.co.uk/v1/widget.js" defer></script>
<script>
  StreetGB.mount("#address-lookup", {
    key: "st_test_your_key",
    onResult: function (address) {
      // address.postcode      normalised postcode
      // address.street        street the customer confirmed
      // address.houseNumber   typed by the customer; never sent to the API
      // address.town, address.lat, address.lng, address.admin
    }
  });
</script>

Fields

FieldTypeMeaning
postcodestringThe postcode, normalised with a single space.
statusstringok, invalid, not_found, or not_covered.
latnumberLatitude of the postcode centroid, WGS84.
lngnumberLongitude of the postcode centroid, WGS84.
streetstring or nullThe street with the largest property share. Null if none could be ranked.
multi_streetbooleanTrue when more than one street has properties on this postcode.
street_candidatesarrayEach street, with name, share (0 to 1) and confidence (high, medium or low).
localitystring or nullDependent locality when the directory has one. Often null in London.
townstringPost town.
countystringCounty, or the unitary area used on addresses.
admin.councilstringLocal authority.
admin.wardstringElectoral ward.
admin.constituencystringWestminster parliamentary constituency.
admin.regionstringEnglish region. Scotland and Wales use the country name.
admin.countrystringEngland, Scotland or Wales.
uprn_countnumberHow many properties the open data places on the postcode. Not their addresses.
house_numberstringAlways "collect from user". The API never returns a house number or name.
sourcesstring arrayOpen datasets used to build the response.

FAQ