Geocoding

Forward geocode a structured address (form-style fields)

Changed on

Convert a structured address (street, city, postal code, country) into a list of matching OpenStreetMap places. Prefer this over /search when you have address components from a form. At least one of street, city, or postalcode is required. Intended for one-shot lookups, not live autocomplete. Data is (C) OpenStreetMap contributors (ODbL 1.0).

get/api/v1/geocoding/structured-search

Request

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

Query parameters

streetstring nullable

Street name with optional house number (e.g. 1600 Pennsylvania Avenue).

citystring nullable

City or locality name.

countystring nullable

County or district name.

statestring nullable

State, province, or region name.

countrystring nullable

Country name or ISO 3166-1 alpha-2 / alpha-3 code.

postalcodestring nullable

Postal code component.

limitinteger

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

addressdetailsboolean

Include the structured address breakdown on every result.

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