Skip to content

GET /search/structured API

  • Geocoding

Structured search using discrete address components.

Accepts individual address attributes to improve parsing accuracy. At least one structured field must be supplied and may be combined with standard filtering parameters such as sources, layers, boundaries, or size.
Parameters
NameInTypeRequiredDescription
addressquerystringNoStreet address including house number when available.
neighbourhoodquerystringNoNeighbourhood component for structured geocoding.
boroughquerystringNoBorough component for structured geocoding.
localityquerystringNoLocality (city or town) component for structured geocoding.
countyquerystringNoCounty or equivalent component for structured geocoding.
regionquerystringNoRegion or state component for structured geocoding.
postalcodequerystringNoPostal code component for structured geocoding.
countryquerystringNoCountry name or ISO code for structured geocoding.
sizequeryintegerNoNumber of results to return. Values above 40 are coerced to 40.
boundary.rect.min_latquerynumberNoSouthern latitude of the rectangular bounding box.
boundary.rect.min_lonquerynumberNoWestern longitude of the rectangular bounding box.
boundary.rect.max_latquerynumberNoNorthern latitude of the rectangular bounding box.
boundary.rect.max_lonquerynumberNoEastern longitude of the rectangular bounding box.
boundary.circle.latquerynumberNoLatitude for the center of the circular boundary filter.
boundary.circle.lonquerynumberNoLongitude for the center of the circular boundary filter.
boundary.circle.radiusquerynumberNoRadius 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.countryquerystringNoRestrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.
boundary.gidquerystringNoPelias global identifier used to restrict results to a parent geography.
sourcesqueryarrayNoComma separated list of data sources to include.
layersqueryarrayNoComma separated list of record layers to include in the response.
  • addressqueryOptional
    Typestring

    Street address including house number when available.

  • neighbourhoodqueryOptional
    Typestring

    Neighbourhood component for structured geocoding.

  • boroughqueryOptional
    Typestring

    Borough component for structured geocoding.

  • localityqueryOptional
    Typestring

    Locality (city or town) component for structured geocoding.

  • countyqueryOptional
    Typestring

    County or equivalent component for structured geocoding.

  • regionqueryOptional
    Typestring

    Region or state component for structured geocoding.

  • postalcodequeryOptional
    Typestring

    Postal code component for structured geocoding.

  • countryqueryOptional
    Typestring

    Country name or ISO code for structured geocoding.

  • sizequeryOptional
    Typeinteger

    Number of results to return. Values above 40 are coerced to 40.

  • boundary.rect.min_latqueryOptional
    Typenumber

    Southern latitude of the rectangular bounding box.

  • boundary.rect.min_lonqueryOptional
    Typenumber

    Western longitude of the rectangular bounding box.

  • boundary.rect.max_latqueryOptional
    Typenumber

    Northern latitude of the rectangular bounding box.

  • boundary.rect.max_lonqueryOptional
    Typenumber

    Eastern longitude of the rectangular bounding box.

  • boundary.circle.latqueryOptional
    Typenumber

    Latitude for the center of the circular boundary filter.

  • boundary.circle.lonqueryOptional
    Typenumber

    Longitude for the center of the circular boundary filter.

  • boundary.circle.radiusqueryOptional
    Typenumber

    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.countryqueryOptional
    Typestring

    Restrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.

  • boundary.gidqueryOptional
    Typestring

    Pelias global identifier used to restrict results to a parent geography.

  • sourcesqueryOptional
    Typearray

    Comma separated list of data sources to include.

  • layersqueryOptional
    Typearray

    Comma separated list of record layers to include in the response.

Sample responses
  • 200 Success — Successful structured geocoding response.

    application/jsonGeoJSONFeatureCollection

    {
    "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/jsonGeoJSONFeatureCollection

    {
    "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/jsonGeoJSONFeatureCollection

    {
    "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/jsonGeoJSONFeatureCollection

    {
    "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

200 OK

Terminal window
# 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'

400 Bad Request

Terminal window
# 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'

408 Request Timeout

Terminal window
# 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'

500 Internal Server Error

Terminal window
# 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'
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.

Query parameters

Street address including house number when available.

Neighbourhood component for structured geocoding.

Borough component for structured geocoding.

Locality (city or town) component for structured geocoding.

County or equivalent component for structured geocoding.

Region or state component for structured geocoding.

Postal code component for structured geocoding.

Country name or ISO code for structured geocoding.

Number of results to return. Values above 40 are coerced to 40.

Southern latitude of the rectangular bounding box.

Western longitude of the rectangular bounding box.

Northern latitude of the rectangular bounding box.

Eastern longitude of the rectangular bounding box.

Latitude for the center of the circular boundary filter.

Longitude for the center of the circular boundary filter.

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.

Restrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.

Pelias global identifier used to restrict results to a parent geography.

Comma separated list of data sources to include.

Comma separated list of record layers to include in the response.

Configure the request and select “Send request” to preview the response.