Weather

Current conditions plus a daily forecast for any coordinate on Earth, or any city in the curated gazetteer.

GET/v1/weather

Authentication

Requires an API key: Authorization: Bearer fg_live_…. Unauthenticated requests receive 401 missing_api_key. See Authentication.

Query parameters

Parameter	Type	Description
lat required*	float	Latitude, `-90` to `90`. Required together with `lon` unless `city` is given.
lon required*	float	Longitude, `-180` to `180`.
city optional	string	City name or slug (e.g. `london`, `San Francisco`) as an alternative to `lat`/`lon`. Unknown names return `404 not_found` — resolve free-form text with geocoding first.
units optional	enum	`metric` (default) or `imperial`. Affects `temp`, `feels_like`, `dew_point`, `temp_max`, `temp_min` (°C/°F) and `wind_speed` (km/h / mph). `precip_mm`, `visibility_km` and `pressure_mb` are always metric.
days optional	integer	Forecast length in days, `1`–`7`. Default `3`.

Example request

bash

curl "https://forge-api.dev/v1/weather?lat=51.51&lon=-0.13&units=metric&days=3" \
  -H "Authorization: Bearer fg_live_YOUR_KEY"

Example response

200 OK — note the envelope: your payload is under data, request metadata under meta.

json

{
  "status": "ok",
  "data": {
    "location": {
      "name": "London",
      "region": "England",
      "country": "GB",
      "lat": 51.5072,
      "lon": -0.1276,
      "timezone": "Europe/London",
      "localtime": "2026-07-14 09:32"
    },
    "current": {
      "temp": 5.8,
      "feels_like": 3,
      "temp_c": 5.8,
      "humidity": 87,
      "dew_point": 3.2,
      "wind_speed": 29.4,
      "wind_deg": 330,
      "wind_dir": "NNW",
      "pressure_mb": 1025,
      "visibility_km": 9.9,
      "cloud_cover": 79,
      "uv_index": 3,
      "precip_mm": 6.5,
      "condition": {
        "code": 1183,
        "text": "Light rain",
        "icon": "rain"
      },
      "observed_at": "2026-07-14T09:30:00.000Z"
    },
    "forecast": {
      "daily": [
        {
          "date": "2026-07-14",
          "temp_max": 9.4,
          "temp_min": 4.6,
          "humidity": 93,
          "cloud_cover": 22,
          "wind_speed": 28.8,
          "precip_mm": 0,
          "precip_prob": 5,
          "uv_index": 4,
          "sunrise": "05:52",
          "sunset": "16:20",
          "condition": {
            "code": 1003,
            "text": "Partly cloudy"
          }
        },
        {
          "date": "2026-07-15",
          "temp_max": 9.5,
          "temp_min": -0.4,
          "humidity": 90,
          "cloud_cover": 24,
          "wind_speed": 5.6,
          "precip_mm": 0,
          "precip_prob": 13,
          "uv_index": 4,
          "sunrise": "06:44",
          "sunset": "18:41",
          "condition": {
            "code": 1003,
            "text": "Partly cloudy"
          }
        },
        {
          "date": "2026-07-16",
          "temp_max": 3.5,
          "temp_min": -1.3,
          "humidity": 83,
          "cloud_cover": 30,
          "wind_speed": 9,
          "precip_mm": 0,
          "precip_prob": 17,
          "uv_index": 4,
          "sunrise": "06:41",
          "sunset": "17:38",
          "condition": {
            "code": 1003,
            "text": "Partly cloudy"
          }
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_5f0c19a2b7d3e481f06a",
    "credits_used": 1,
    "generated_at": "2026-07-14T09:32:11.412Z",
    "units": "metric"
  }
}

Response fields

Field	Type	Description
data.location	object	Resolved place. `name`/`region`/`country` come from the nearest gazetteer city (within ~2°); for remote coordinates `name` falls back to `"lat,lon"` and `region`/`country` are `null`.
data.current.temp	float	Air temperature in the requested units.
data.current.temp_c	float	Legacy duplicate of the temperature, always Celsius, kept for v0-era integrations. Prefer `temp`.
data.current.condition	object	`{code, text, icon}`. Codes are stable integers (e.g. `1000` Clear, `1195` Heavy rain); see Data & coverage.
data.current.observed_at	string	ISO 8601 UTC timestamp of the observation cycle (10-minute resolution).
data.forecast.daily[]	array	One entry per day starting today (UTC): `date`, `temp_max`, `temp_min`, `humidity`, `cloud_cover`, `wind_speed`, `precip_mm`, `precip_prob`, `uv_index`, `sunrise`, `sunset`, `condition`.
meta.request_id	string	Unique per request; include it in support tickets.
meta.credits_used	int	Billing units consumed (currently always `1`).

Errors

400 invalid_params — malformed lat/lon, units outside the enum, days out of range.
401 missing_api_key / invalid_api_key
404 not_found — unknown city name.
429 rate_limited — see Rate limits.

Full error semantics: Errors.