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
| HTTP | status | When |
|---|---|---|
| 200 | ok | Postcode found in Great Britain |
| 400 | invalid | Not a UK postcode |
| 404 | not_found | Well-formed GB postcode with no open-data record |
| 422 | not_covered | Northern Ireland (BT) |
| 401 | unauthorized | Missing or wrong key |
| 429 | quota_exceeded | Free 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
| Field | Type | Meaning |
|---|---|---|
| postcode | string | The postcode, normalised with a single space. |
| status | string | ok, invalid, not_found, or not_covered. |
| lat | number | Latitude of the postcode centroid, WGS84. |
| lng | number | Longitude of the postcode centroid, WGS84. |
| street | string or null | The street with the largest property share. Null if none could be ranked. |
| multi_street | boolean | True when more than one street has properties on this postcode. |
| street_candidates | array | Each street, with name, share (0 to 1) and confidence (high, medium or low). |
| locality | string or null | Dependent locality when the directory has one. Often null in London. |
| town | string | Post town. |
| county | string | County, or the unitary area used on addresses. |
| admin.council | string | Local authority. |
| admin.ward | string | Electoral ward. |
| admin.constituency | string | Westminster parliamentary constituency. |
| admin.region | string | English region. Scotland and Wales use the country name. |
| admin.country | string | England, Scotland or Wales. |
| uprn_count | number | How many properties the open data places on the postcode. Not their addresses. |
| house_number | string | Always "collect from user". The API never returns a house number or name. |
| sources | string array | Open datasets used to build the response. |