curl --request GET \
--url https://api.ctrl-hub.com/v3/street-search-results \
--header 'X-Session-Token: <api-key>'import requests
url = "https://api.ctrl-hub.com/v3/street-search-results"
headers = {"X-Session-Token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};
fetch('https://api.ctrl-hub.com/v3/street-search-results', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ctrl-hub.com/v3/street-search-results",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Session-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.ctrl-hub.com/v3/street-search-results"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Session-Token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.ctrl-hub.com/v3/street-search-results")
.header("X-Session-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/street-search-results")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "<string>",
"type": "street-search-results",
"attributes": {
"usrn": 123,
"name": "<string>",
"town": "<string>"
}
}
],
"meta": {
"pagination": {
"counts": {
"pages": 1,
"resources": 1
},
"current_page": 1,
"offsets": {
"next": null,
"previous": null
},
"requested": {
"limit": 10,
"offset": 0
}
},
"features": {
"include": {
"options": [
"related.resource"
]
}
},
"stats": {
"attribution": "<string>"
}
},
"jsonapi": {
"version": "1.0"
}
}{
"id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
"status": "400",
"title": "A validation error was encountered",
"source": {
"parameter": "include"
},
"meta": {
"resource": "wrong_value"
}
}{
"id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
"status": "401",
"title": "You are not authorised to access this resource",
"detail": "In order to access this resource, you need the 'admin' role.",
"code": "AUTH.001"
}{
"id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
"status": "500",
"title": "Internal Server Error",
"detail": "An unexpected error occurred on the server."
}Search for streets
Search the national street gazetteer by street name.
Unlike listing streets, which returns only streets already held, this asks the gazetteer and so finds streets no permit has ever touched. Results are ordered by the provider’s relevance; there is no score to sort on.
Paging is by cursor. The gazetteer can continue after a street it has
already returned, but it cannot skip to the nth result. So the first page is
asked for with no cursor, and each page after it with an after filter naming
the USRN of the last street on the page before:
and(eq(term,"bentinck road"),eq(after,15003853)). offset still numbers the
page in the response meta, but does not fetch one: an offset above zero with
no after is a 400, as is an after that is not in this term’s results.
limit is capped at 50. The count in the response is the number of streets
matching the term, not the size of the page.
Gazetteer data must be acknowledged wherever it is shown. A name search and a
USRN lookup both answer from OS open data, and return that acknowledgement as
meta.stats.attribution, to be displayed with the results as given.
A USRN term (digits only) is a lookup, not a search: it returns at most one street, and there is never a second page.
Every street returned is recorded before the response is sent, so each id
can be fetched from /v3/geo/streets/{street_id} straight away. A street
recorded this way has its USRN, name and town. A street already held gains
the search’s name and town only where its own are empty; nothing else of it
changes.
curl --request GET \
--url https://api.ctrl-hub.com/v3/street-search-results \
--header 'X-Session-Token: <api-key>'import requests
url = "https://api.ctrl-hub.com/v3/street-search-results"
headers = {"X-Session-Token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};
fetch('https://api.ctrl-hub.com/v3/street-search-results', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ctrl-hub.com/v3/street-search-results",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Session-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.ctrl-hub.com/v3/street-search-results"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Session-Token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.ctrl-hub.com/v3/street-search-results")
.header("X-Session-Token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ctrl-hub.com/v3/street-search-results")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "<string>",
"type": "street-search-results",
"attributes": {
"usrn": 123,
"name": "<string>",
"town": "<string>"
}
}
],
"meta": {
"pagination": {
"counts": {
"pages": 1,
"resources": 1
},
"current_page": 1,
"offsets": {
"next": null,
"previous": null
},
"requested": {
"limit": 10,
"offset": 0
}
},
"features": {
"include": {
"options": [
"related.resource"
]
}
},
"stats": {
"attribution": "<string>"
}
},
"jsonapi": {
"version": "1.0"
}
}{
"id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
"status": "400",
"title": "A validation error was encountered",
"source": {
"parameter": "include"
},
"meta": {
"resource": "wrong_value"
}
}{
"id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
"status": "401",
"title": "You are not authorised to access this resource",
"detail": "In order to access this resource, you need the 'admin' role.",
"code": "AUTH.001"
}{
"id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
"status": "500",
"title": "Internal Server Error",
"detail": "An unexpected error occurred on the server."
}Authorizations
Session token for authentication.
Query Parameters
Filters the response data based on the value provided.
A term filter is required; without one the search returns nothing rather
than every street in the country. A term of digits only is a USRN, and is
looked up rather than searched for: it returns at most one street. Any other
term is passed to the gazetteer as a street name query.
An after filter, naming the USRN of the last street on the previous page,
asks for the next page: and(eq(term,"high street"),eq(after,42502279)).
For more information on using named filters, see the docs
Limit the number of resources returned by the API
x >= 1Offset the resources returned by the API
x >= 0