Structured Search

Structured search accepts well-formed address attributes instead of a single text field. Use it when you already have separate house number, street, locality, and region values and want to avoid ambiguities introduced by free-form parsing.

OpenAPI links

See GET /search/structured for admissible fields, shared filters, and response schemas.

Try it: GET /search/structured

Address fields

Provide any combination of the following fields. At least one field is required, and more context improves match confidence.

Field	Example	Notes
address	30 West 26th Street	Full street line including house number.
locality	New York	City or town component.
region	NY	State, province, or region.
country	US	Country name or ISO code.
postalcode	10010	Optional postal or ZIP code.
county, borough, neighbourhood	Manhattan, Chelsea	Supply when you have finer-grained administrative info.

All structured queries also accept the shared filters from forward search: size, sources, layers, boundary.*, and boundary.country.

Usage tips

• Include country whenever possible to improve ranking, especially for short street names.
• Pair postalcode with address to disambiguate duplicate street numbers across districts.
• Structured search falls back to Pelias parsing for missing components; providing more fields reduces the chance of ambiguous matches.

Sample request

cURL

curl -s -G 'https://api-na.geobridge.io/v1/search/structured' \
  -H 'Accept: application/json' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" \
  --data-urlencode 'address=30 West 26th Street' \
  --data-urlencode 'locality=New York' \
  --data-urlencode 'region=NY' \
  --data-urlencode 'country=US'

Node.js

const apiKey = process.env.GEOBRIDGE_API_KEY;
const params = new URLSearchParams({
  address: '30 West 26th Street',
  locality: 'New York',
  region: 'NY',
  country: 'US',
});
const url = `https://api-na.geobridge.io/v1/search/structured?${params.toString()}`;

const response = await fetch(url, {
  headers: {
    Accept: 'application/json',
    'X-API-Key': apiKey,
  },
  signal: AbortSignal.timeout(10000),
});

if (!response.ok) {
  throw new Error(`Structured search failed: ${response.status} ${response.statusText}`);
}

const payload = await response.json();
console.log(payload.features[0]?.properties?.label);

Python

import os
import requests

api_key = os.environ["GEOBRIDGE_API_KEY"]

resp = requests.get(
    "https://api-na.geobridge.io/v1/search/structured",
    headers={
        "Accept": "application/json",
        "X-API-Key": api_key,
    },
    params={
        "address": "30 West 26th Street",
        "locality": "New York",
        "region": "NY",
        "country": "US",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json()["geocoding"]["query"])

Validation reminders

• Requests without any structured fields return HTTP 400. Validate input before calling the API.
• size obeys the same 40-result ceiling as other Pelias endpoints; larger values are coerced and emit a warning in geocoding.warnings.
• Combine structured search with /place to fetch authoritative details for the returned gid identifiers.