Forward Search

Use GET /v1/search to translate user-entered text into ranked matches sourced from OpenStreetMap, OpenAddresses, Who’s On First, and Geonames. Forward search prioritises relevance, confidence, and proximity so you can drop results straight into maps or downstream pipelines.

OpenAPI links

See GET /search for required query parameters, schema definitions, and error responses.

Try it: GET /search

Query parameters

Name	Required	Description
text	Yes	Free-form query string from the user (1–512 characters).
size	No	Number of results to return (1–40, default 10). Values above 40 are coerced to 40.
focus.point.lat, focus.point.lon	No	Bias ranking toward a latitude/longitude pair without discarding global matches.
boundary.circle.lat, boundary.circle.lon, boundary.circle.radius	No	Keep results within a circle in kilometers (default 50 km). Combine with focus to emphasise nearby matches.
boundary.rect.min_lat, boundary.rect.min_lon, boundary.rect.max_lat, boundary.rect.max_lon	No	Filter results to a rectangular bounding box.
boundary.country, boundary.gid	No	Restrict output to specific ISO codes or a parent Pelias gid.
sources, layers	No	Limit responses to particular data providers or feature layers (for example layers=address,street).

Biasing relevance

• Pair a focus point with a modest size (5–10) to keep the most local matches first.
• Switch between boundary.circle and boundary.rect.* depending on whether you have a radial search or well-defined view bounds.
• Whitelist layers when you only care about certain feature types (for example street versus venue).
• Use boundary.country with multi-region deployments to avoid mixing jurisdictions in the same response.

Sample request

cURL

curl -s -G 'https://api-na.geobridge.io/v1/search' \
  -H 'Accept: application/json' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" \
  --data-urlencode 'text=Union Square' \
  --data-urlencode 'size=5' \
  --data-urlencode 'focus.point.lat=40.7359' \
  --data-urlencode 'focus.point.lon=-73.9911'

Node.js

const apiKey = process.env.GEOBRIDGE_API_KEY;
const params = new URLSearchParams({
  text: 'Union Square',
  size: '5',
  'focus.point.lat': '40.7359',
  'focus.point.lon': '-73.9911',
});
const url = `https://api-na.geobridge.io/v1/search?${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(`Search failed: ${response.status} ${response.statusText}`);
}

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

Python

import os
import requests

api_key = os.environ["GEOBRIDGE_API_KEY"]

resp = requests.get(
    "https://api-na.geobridge.io/v1/search",
    headers={
        "Accept": "application/json",
        "X-API-Key": api_key,
    },
    params={
        "text": "Union Square",
        "size": 5,
        "focus.point.lat": 40.7359,
        "focus.point.lon": -73.9911,
    },
    timeout=10,
)
resp.raise_for_status()

for feature in resp.json().get("features", []):
    print(feature["properties"]["label"])

Response structure

Forward search returns a GeoJSON FeatureCollection with Pelias metadata in the geocoding block. Each feature exposes canonical hierarchy details and a confidence value so you can tune downstream ranking.

{
  "type": "FeatureCollection",
  "geocoding": {
    "query": {
      "text": "Union Square",
      "size": 5
    },
    "warnings": []
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "label": "Union Square, Manhattan, NY, USA",
        "gid": "whosonfirst:neighbourhood:85869245",
        "layer": "neighbourhood",
        "source": "whosonfirst",
        "confidence": 0.94
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-73.9911, 40.7359]
      }
    }
  ]
}

Error handling

• Validation errors (HTTP 400) surface when the text parameter is missing, empty, or exceeds length limits.
• Pelias may time out during heavy load (HTTP 408). Retry with exponential backoff or relax filters such as size and radius.
• Transient server issues return HTTP 5xx. Treat these as retryable before failing a user action.