forge
Sign in Get your API key

Geocoding

Turn free-form place text into coordinates you can feed to /v1/weather. Search is prefix-and-substring over the curated gazetteer, ranked by match quality then population.

GET/v1/geocode

Query parameters

ParameterTypeDescription
q requiredstringSearch text, e.g. san, berlin.
limit optionalintegerMax results, 1–10. Default 5.

Example request

bash
curl "https://forge-api.dev/v1/geocode?q=san&limit=3" \
  -H "Authorization: Bearer fg_live_YOUR_KEY"

Example response

json
{
  "status": "ok",
  "data": {
    "query": "san",
    "results": [
      {
        "id": "santiago",
        "name": "Santiago",
        "region": "Santiago Metropolitan",
        "country": "CL",
        "lat": -33.4489,
        "lon": -70.6693,
        "timezone": "America/Santiago",
        "population": 6257516
      },
      {
        "id": "san-francisco",
        "name": "San Francisco",
        "region": "California",
        "country": "US",
        "lat": 37.7749,
        "lon": -122.4194,
        "timezone": "America/Los_Angeles",
        "population": 873965
      }
    ]
  },
  "meta": {
    "request_id": "req_a01f4c3db2e895671c30",
    "credits_used": 1,
    "generated_at": "2026-07-14T09:33:02.190Z",
    "result_count": 3
  }
}

An unmatched query is not an error: you get 200 with an empty results array and meta.result_count: 0.

Errors