Geocoding

Forward geocode a free-text query

Changed on

Convert a free-text query (city name, address, landmark) into a list of matching OpenStreetMap places with coordinates and optional address breakdown. Intended for one-shot lookups, not live autocomplete - OSM policy prohibits as-you-type usage against the public Nominatim instance. Data is (C) OpenStreetMap contributors (ODbL 1.0).

get/api/v1/geocoding/search

Request

  • Base URL: https://sugra.ai
  • URL: https://sugra.ai/api/v1/geocoding/search
  • Auth: API key in header x-api-key

Query parameters

qstring required

Free-text query (city name, address, landmark).

countrystring nullable

Comma-separated ISO 3166-1 alpha-2 country codes to restrict results (e.g. US,GB,DE).

limitinteger

Maximum number of results to return (1-50).

addressdetailsboolean

Include the structured address breakdown on every result.

viewboxstring nullable

Optional bias bounding box minLon,minLat,maxLon,maxLat. When set, results are restricted to this box.

Response

Matching places sorted by importance, (C) OpenStreetMap contributors (ODbL 1.0).

Example response

{
  "meta": {
    "endpoint": "/api/v1/fred/us/cpi",
    "data_time": "2026-04-16T14:30:00Z",
    "response_time": "2026-04-16T14:30:12Z",
    "provider": "Sugra API v1.0.1",
    "data_age_days": 8.532,
    "source": "sugra_crypto",
    "attribution": "Short interest and Reg SHO daily short volume data is owned by and sourced from FINRA (Financial Industry Regulatory Authority).",
    "fallback_chain": [
      "sugra_crypto",
      "sugra_finance"
    ],
    "stale_since": "2026-09-08T12:00:00Z",
    "period": "2026-Q1",
    "notes": "the UKMTO report behind these counts is dated 2026-08-21 and is 11 days old"
  }
}

Changes