Reverse Geocoding

Reverse geocoding enumerates the features nearest to a latitude/longitude pair. Use it to name map clicks, convert GPS traces into addresses, or infer hierarchy metadata from telemetry.

OpenAPI links

See GET /reverse for the full parameter list, validation rules, and status codes.

Try it: GET /reverse

Query parameters

Name	Required	Description
point.lat, point.lon	Yes	Coordinates to resolve. Latitudes must be between -90 and 90, longitudes between -180 and 180.
size	No	Number of candidates to return (1–40, default 10).
boundary.circle.radius	No	Search radius in kilometers (0.1–5). Defaults to 1 km and caps at 5 km.
boundary.country, boundary.gid	No	Restrict results to ISO-3166 codes or a Pelias gid ancestor.
sources, layers	No	Filter responses to specific data providers or feature layers.

Tuning proximity

• Tighten boundary.circle.radius to avoid city-level results when users expect the nearest address.
• Provide both sources and layers when you only trust certain datasets for address-level accuracy.
• Thin the candidate list with size=1 or size=3 to cut response times for high-volume workloads.
• Use boundary.gid when you already know the containing administrative boundary from a previous query.

Sample request

cURL

curl -s -G 'https://api-na.geobridge.io/v1/reverse' \
  -H 'Accept: application/json' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" \
  --data-urlencode 'point.lat=48.858268' \
  --data-urlencode 'point.lon=2.294471' \
  --data-urlencode 'size=3' \
  --data-urlencode 'layers=address'

Node.js

const apiKey = process.env.GEOBRIDGE_API_KEY;
const params = new URLSearchParams({
  'point.lat': '48.858268',
  'point.lon': '2.294471',
  size: '3',
  layers: 'address',
});
const url = `https://api-na.geobridge.io/v1/reverse?${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(`Reverse geocoding failed: ${response.status} ${response.statusText}`);
}

const payload = await response.json();
for (const feature of payload.features ?? []) {
  console.log(feature.properties.label, feature.properties.distance);
}

Python

import os
import requests

api_key = os.environ["GEOBRIDGE_API_KEY"]

resp = requests.get(
    "https://api-na.geobridge.io/v1/reverse",
    headers={
        "Accept": "application/json",
        "X-API-Key": api_key,
    },
    params={
        "point.lat": 48.858268,
        "point.lon": 2.294471,
        "size": 3,
        "layers": "address",
    },
    timeout=10,
)
resp.raise_for_status()

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

Response structure

Reverse geocoding also returns a GeoJSON FeatureCollection. Each feature.properties record includes a distance field (kilometers) describing how far the result is from the query point and a confidence score to help you reject weak matches.

Operational guidance

• Invalid coordinates trigger an HTTP 400 response. Validate inputs before calling the API to avoid productive retries.
• Requests that exceed the five kilometer radius ceiling are coerced to 5 km and emit a Pelias warning in the geocoding metadata. Inspect geocoding.warnings during debugging.
• Timeouts (HTTP 408) and transient server errors (HTTP 5xx) are safe to retry with exponential backoff.