GET /search/structured API
GET/search/structured
Section titled “GET/search/structured”Structured search using discrete address components.
Parameters
Parameters
Section titled “ Parameters ”| Name | In | Type | Required | Description |
|---|---|---|---|---|
address | query | string | No | Street address including house number when available. |
neighbourhood | query | string | No | Neighbourhood component for structured geocoding. |
borough | query | string | No | Borough component for structured geocoding. |
locality | query | string | No | Locality (city or town) component for structured geocoding. |
county | query | string | No | County or equivalent component for structured geocoding. |
region | query | string | No | Region or state component for structured geocoding. |
postalcode | query | string | No | Postal code component for structured geocoding. |
country | query | string | No | Country name or ISO code for structured geocoding. |
size | query | integer | No | Number of results to return. Values above 40 are coerced to 40. |
boundary.rect.min_lat | query | number | No | Southern latitude of the rectangular bounding box. |
boundary.rect.min_lon | query | number | No | Western longitude of the rectangular bounding box. |
boundary.rect.max_lat | query | number | No | Northern latitude of the rectangular bounding box. |
boundary.rect.max_lon | query | number | No | Eastern longitude of the rectangular bounding box. |
boundary.circle.lat | query | number | No | Latitude for the center of the circular boundary filter. |
boundary.circle.lon | query | number | No | Longitude for the center of the circular boundary filter. |
boundary.circle.radius | query | number | No | Radius in kilometers for circular boundary filtering. Defaults to 50 for search and autocomplete, and 1 for reverse. Reverse queries cap the value at 5 km. |
boundary.country | query | string | No | Restrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries. |
boundary.gid | query | string | No | Pelias global identifier used to restrict results to a parent geography. |
sources | query | array | No | Comma separated list of data sources to include. |
layers | query | array | No | Comma separated list of record layers to include in the response. |
addressqueryOptionalStreet address including house number when available.
neighbourhoodqueryOptionalNeighbourhood component for structured geocoding.
boroughqueryOptionalBorough component for structured geocoding.
localityqueryOptionalLocality (city or town) component for structured geocoding.
countyqueryOptionalCounty or equivalent component for structured geocoding.
regionqueryOptionalRegion or state component for structured geocoding.
postalcodequeryOptionalPostal code component for structured geocoding.
countryqueryOptionalCountry name or ISO code for structured geocoding.
sizequeryOptionalNumber of results to return. Values above 40 are coerced to 40.
boundary.rect.min_latqueryOptionalSouthern latitude of the rectangular bounding box.
boundary.rect.min_lonqueryOptionalWestern longitude of the rectangular bounding box.
boundary.rect.max_latqueryOptionalNorthern latitude of the rectangular bounding box.
boundary.rect.max_lonqueryOptionalEastern longitude of the rectangular bounding box.
boundary.circle.latqueryOptionalLatitude for the center of the circular boundary filter.
boundary.circle.lonqueryOptionalLongitude for the center of the circular boundary filter.
boundary.circle.radiusqueryOptionalRadius in kilometers for circular boundary filtering. Defaults to 50 for search and autocomplete, and 1 for reverse. Reverse queries cap the value at 5 km.
boundary.countryqueryOptionalRestrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.
boundary.gidqueryOptionalPelias global identifier used to restrict results to a parent geography.
sourcesqueryOptionalComma separated list of data sources to include.
layersqueryOptionalComma separated list of record layers to include in the response.
Sample responses
Sample responses
Section titled “ Sample responses ”- 200 Success — Successful structured geocoding response.
application/json → GeoJSONFeatureCollection
{"type": "FeatureCollection","geocoding": {"version": "1.0.0","timestamp": "2024-03-18T12:36:48Z","engine": {"name": "pelias","author": "geobridge","version": "2.14.0"},"query": {"structured": {"address": "30 West 26th Street","locality": "New York","region": "NY","country": "US"},"size": 1}},"features": [{"type": "Feature","geometry": {"type": "Point","coordinates": [-73.989708,40.744026]},"properties": {"id": "oa-nyc-30-w-26th","gid": "openaddresses:address:us/ny/new-york/citywide/30-west-26th-street","layer": "address","source": "openaddresses","name": "30 West 26th Street","label": "30 West 26th Street, Manhattan, New York, NY, USA","housenumber": "30","street": "West 26th Street","confidence": 0.95,"accuracy": "point","continent": "North America","country": "United States","country_a": "USA","region": "New York","county": "New York County","locality": "New York","neighbourhood": "NoMad","postalcode": "10010"}}]}Structured address lookup with a precise match.
- 400 Client error — Invalid input parameters supplied.
application/json → GeoJSONFeatureCollection
{"type": "FeatureCollection","geocoding": {"version": "1.0.0","timestamp": "2024-03-18T12:36:48Z","query": {"structured": {}},"errors": [{"code": "MISSING_STRUCTURED_FIELDS","message": "Provide at least one structured address component."}]},"features": []}Request omitted all structured components.
- 408 Client error — Upstream search engine timeout.
application/json → GeoJSONFeatureCollection
{"type": "FeatureCollection","geocoding": {"version": "1.0.0","query": {"structured": {"address": "30 West 26th Street","locality": "New York"}},"errors": [{"code": "TIMEOUT","message": "Structured search exceeded the 1500 ms timeout window."}],"warnings": [{"code": "RETRY_REQUEST","message": "Retry shortly or lower the requested result size."}]},"features": []}Structured search timeout example.
- 500 Server error — Unexpected server error.
application/json → GeoJSONFeatureCollection
{"type": "FeatureCollection","geocoding": {"version": "1.0.0","query": {"structured": {"address": "30 West 26th Street","locality": "New York"}},"errors": [{"code": "INTERNAL_SERVER_ERROR","message": "Unexpected exception executing structured search pipeline."}]},"features": []}Unexpected backend failure during structured search.
Code samples
Code samples
Section titled “ Code samples ”200 OK
# 200 OK — Structured lookup combining address, locality, region, and country.curl -s -G 'https://api-na.geobridge.io/v1/search/structured' \ -H 'Accept: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ --data-urlencode 'address=30 West 26th Street' \ --data-urlencode 'locality=New York' \ --data-urlencode 'region=NY' \ --data-urlencode 'country=US'// 200 OK — Structured lookup combining address, locality, region, and country.// Node.js 18+ with global fetch support.const params = new URLSearchParams({ "address": "30 West 26th Street", "locality": "New York", "region": "NY", "country": "US"});const requestUrl = `https://api-na.geobridge.io/v1/search/structured` + `?${params.toString()}`;const response = await fetch(requestUrl, { method: 'GET', headers: { 'X-API-Key': 'YOUR_API_KEY' }, signal: AbortSignal.timeout(10000)});console.log(response.status);const payload = await response.text();console.log(payload);# 200 OK — Structured lookup combining address, locality, region, and country.import requests
url = 'https://api-na.geobridge.io/v1/search/structured'params = { "address": "30 West 26th Street", "locality": "New York", "region": "NY", "country": "US"}headers = { "X-API-Key": "YOUR_API_KEY"}payload = Noneresponse = requests.get(url, params=params, headers=headers, timeout=10)print(response.status_code)
try: print(response.json())except ValueError: print(response.text)// 200 OK — Structured lookup combining address, locality, region, and country.package main
import ( "fmt" "io" "log" "net/http" "net/url" "time")
func main() { client := &http.Client{Timeout: 10 * time.Second} u, err := url.Parse("https://api-na.geobridge.io/v1/search/structured") if err != nil { log.Fatal(err) } q := u.Query() q.Set("address", "30 West 26th Street") q.Set("locality", "New York") q.Set("region", "NY") q.Set("country", "US") u.RawQuery = q.Encode() req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { log.Fatal(err) } req.Header.Set("Accept", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := client.Do(req) if err != nil { log.Fatal(err) } defer resp.Body.Close() fmt.Println(resp.StatusCode) payload, _ := io.ReadAll(resp.Body) fmt.Println(string(payload))}// 200 OK — Structured lookup combining address, locality, region, and country.import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.time.Duration;
public class Example { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-na.geobridge.io/v1/search/structured?address=30+West+26th+Street&locality=New+York®ion=NY&country=US")) .header("Accept", "application/json") .header("X-API-Key", "YOUR_API_KEY") .method("GET", HttpRequest.BodyPublishers.noBody()) .timeout(Duration.ofSeconds(10)) .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); }}// 200 OK — Structured lookup combining address, locality, region, and country.using System;using System.Net.Http;using System.Text;using System.Threading.Tasks;
class Program{ static async Task Main() { using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/search/structured?address=30+West+26th+Street&locality=New+York®ion=NY&country=US"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("X-API-Key", "YOUR_API_KEY"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); }}400 Bad Request
# 400 Bad Request — Omitting structured fields results in validation failure.curl -s -X GET 'https://api-na.geobridge.io/v1/search/structured' \ -H 'Accept: application/json' \ -H 'X-API-Key: YOUR_API_KEY'// 400 Bad Request — Omitting structured fields results in validation failure.// Node.js 18+ with global fetch support.const requestUrl = 'https://api-na.geobridge.io/v1/search/structured';const response = await fetch(requestUrl, { method: 'GET', headers: { 'X-API-Key': 'YOUR_API_KEY' }, signal: AbortSignal.timeout(10000)});console.log(response.status);const payload = await response.text();console.log(payload);# 400 Bad Request — Omitting structured fields results in validation failure.import requests
url = 'https://api-na.geobridge.io/v1/search/structured'params = Noneheaders = { "X-API-Key": "YOUR_API_KEY"}payload = Noneresponse = requests.get(url, params=params, headers=headers, timeout=10)print(response.status_code)
try: print(response.json())except ValueError: print(response.text)// 400 Bad Request — Omitting structured fields results in validation failure.package main
import ( "fmt" "io" "log" "net/http" "net/url" "time")
func main() { client := &http.Client{Timeout: 10 * time.Second} u, err := url.Parse("https://api-na.geobridge.io/v1/search/structured") if err != nil { log.Fatal(err) } req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { log.Fatal(err) } req.Header.Set("Accept", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := client.Do(req) if err != nil { log.Fatal(err) } defer resp.Body.Close() fmt.Println(resp.StatusCode) payload, _ := io.ReadAll(resp.Body) fmt.Println(string(payload))}// 400 Bad Request — Omitting structured fields results in validation failure.import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.time.Duration;
public class Example { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-na.geobridge.io/v1/search/structured")) .header("Accept", "application/json") .header("X-API-Key", "YOUR_API_KEY") .method("GET", HttpRequest.BodyPublishers.noBody()) .timeout(Duration.ofSeconds(10)) .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); }}// 400 Bad Request — Omitting structured fields results in validation failure.using System;using System.Net.Http;using System.Text;using System.Threading.Tasks;
class Program{ static async Task Main() { using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/search/structured"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("X-API-Key", "YOUR_API_KEY"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); }}408 Request Timeout
# 408 Request Timeout — Structured search example with timeout handling.curl -s -G 'https://api-na.geobridge.io/v1/search/structured' \ -H 'Accept: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ --data-urlencode 'address=30 West 26th Street' \ --data-urlencode 'locality=New York' \ --data-urlencode 'region=NY'// 408 Request Timeout — Structured search example with timeout handling.// Node.js 18+ with global fetch support.const params = new URLSearchParams({ "address": "30 West 26th Street", "locality": "New York", "region": "NY"});const requestUrl = `https://api-na.geobridge.io/v1/search/structured` + `?${params.toString()}`;const response = await fetch(requestUrl, { method: 'GET', headers: { 'X-API-Key': 'YOUR_API_KEY' }, signal: AbortSignal.timeout(10000)});console.log(response.status);const payload = await response.text();console.log(payload);# 408 Request Timeout — Structured search example with timeout handling.import requests
url = 'https://api-na.geobridge.io/v1/search/structured'params = { "address": "30 West 26th Street", "locality": "New York", "region": "NY"}headers = { "X-API-Key": "YOUR_API_KEY"}payload = Noneresponse = requests.get(url, params=params, headers=headers, timeout=10)print(response.status_code)
try: print(response.json())except ValueError: print(response.text)// 408 Request Timeout — Structured search example with timeout handling.package main
import ( "fmt" "io" "log" "net/http" "net/url" "time")
func main() { client := &http.Client{Timeout: 10 * time.Second} u, err := url.Parse("https://api-na.geobridge.io/v1/search/structured") if err != nil { log.Fatal(err) } q := u.Query() q.Set("address", "30 West 26th Street") q.Set("locality", "New York") q.Set("region", "NY") u.RawQuery = q.Encode() req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { log.Fatal(err) } req.Header.Set("Accept", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := client.Do(req) if err != nil { log.Fatal(err) } defer resp.Body.Close() fmt.Println(resp.StatusCode) payload, _ := io.ReadAll(resp.Body) fmt.Println(string(payload))}// 408 Request Timeout — Structured search example with timeout handling.import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.time.Duration;
public class Example { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-na.geobridge.io/v1/search/structured?address=30+West+26th+Street&locality=New+York®ion=NY")) .header("Accept", "application/json") .header("X-API-Key", "YOUR_API_KEY") .method("GET", HttpRequest.BodyPublishers.noBody()) .timeout(Duration.ofSeconds(10)) .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); }}// 408 Request Timeout — Structured search example with timeout handling.using System;using System.Net.Http;using System.Text;using System.Threading.Tasks;
class Program{ static async Task Main() { using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/search/structured?address=30+West+26th+Street&locality=New+York®ion=NY"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("X-API-Key", "YOUR_API_KEY"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); }}500 Internal Server Error
# 500 Internal Server Error — Structured search gracefully handling a server error.curl -s -G 'https://api-na.geobridge.io/v1/search/structured' \ -H 'Accept: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ --data-urlencode 'address=30 West 26th Street' \ --data-urlencode 'locality=New York' \ --data-urlencode 'region=NY'// 500 Internal Server Error — Structured search gracefully handling a server error.// Node.js 18+ with global fetch support.const params = new URLSearchParams({ "address": "30 West 26th Street", "locality": "New York", "region": "NY"});const requestUrl = `https://api-na.geobridge.io/v1/search/structured` + `?${params.toString()}`;const response = await fetch(requestUrl, { method: 'GET', headers: { 'X-API-Key': 'YOUR_API_KEY' }, signal: AbortSignal.timeout(10000)});console.log(response.status);const payload = await response.text();console.log(payload);# 500 Internal Server Error — Structured search gracefully handling a server error.import requests
url = 'https://api-na.geobridge.io/v1/search/structured'params = { "address": "30 West 26th Street", "locality": "New York", "region": "NY"}headers = { "X-API-Key": "YOUR_API_KEY"}payload = Noneresponse = requests.get(url, params=params, headers=headers, timeout=10)print(response.status_code)
try: print(response.json())except ValueError: print(response.text)// 500 Internal Server Error — Structured search gracefully handling a server error.package main
import ( "fmt" "io" "log" "net/http" "net/url" "time")
func main() { client := &http.Client{Timeout: 10 * time.Second} u, err := url.Parse("https://api-na.geobridge.io/v1/search/structured") if err != nil { log.Fatal(err) } q := u.Query() q.Set("address", "30 West 26th Street") q.Set("locality", "New York") q.Set("region", "NY") u.RawQuery = q.Encode() req, err := http.NewRequest(http.MethodGet, u.String(), nil) if err != nil { log.Fatal(err) } req.Header.Set("Accept", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := client.Do(req) if err != nil { log.Fatal(err) } defer resp.Body.Close() fmt.Println(resp.StatusCode) payload, _ := io.ReadAll(resp.Body) fmt.Println(string(payload))}// 500 Internal Server Error — Structured search gracefully handling a server error.import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.time.Duration;
public class Example { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api-na.geobridge.io/v1/search/structured?address=30+West+26th+Street&locality=New+York®ion=NY")) .header("Accept", "application/json") .header("X-API-Key", "YOUR_API_KEY") .method("GET", HttpRequest.BodyPublishers.noBody()) .timeout(Duration.ofSeconds(10)) .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode()); System.out.println(response.body()); }}// 500 Internal Server Error — Structured search gracefully handling a server error.using System;using System.Net.Http;using System.Text;using System.Threading.Tasks;
class Program{ static async Task Main() { using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/search/structured?address=30+West+26th+Street&locality=New+York®ion=NY"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("X-API-Key", "YOUR_API_KEY"); var response = await client.SendAsync(request); Console.WriteLine((int)response.StatusCode); Console.WriteLine(await response.Content.ReadAsStringAsync()); }}Try it live
Try it live
Section titled “ Try it live ”Save your API key once and reuse it across endpoints. Configure the request below and send it directly from the docs.
Stored locally in your browser. Removing it clears access for this device.
Configure the request and select “Send request” to preview the response.