{
  "spec": "onecall3.v0",
  "product": "onecall3",
  "title": "One Call 3.0 weather data",
  "provider": "OpenWeather",
  "status": "v0 — this version documents the routes, request contract and the platform envelope of every response. A per-field schema of the payload itself arrives with a later version; until then the payload is the supplier's document, passed through verbatim except for the additions and rewrites listed under response.body.",
  "base_url": "https://data.forum.bot",
  "authentication": "Authorization: Bearer <key> — any active Forum key; every account may call every served product, funded from its one budget; credentials never appear in URLs",
  "routes": [
    "/onecall3/forecast",
    "/onecall3/timemachine",
    "/onecall3/day_summary",
    "/onecall3/overview"
  ],
  "caching": {
    "/onecall3/forecast": "answers may be shared for up to 60 s",
    "/onecall3/timemachine": "answers may be shared for up to 60 s",
    "/onecall3/day_summary": "answers may be shared for up to 60 s",
    "/onecall3/overview": "answers may be shared for up to 60 s"
  },
  "request": {
    "required": {
      "lat": "latitude, decimal degrees",
      "lon": "longitude, decimal degrees"
    },
    "other_parameters": "passed through to the supplier's API unchanged; their names, values and unit conventions follow the supplier's own documentation",
    "closed_surface": "any route not listed above answers 404 not_found — nothing falls through to an origin by accident"
  },
  "response": {
    "headers": {
      "X-Request-Id": "identity of this exact call; quote it to support",
      "X-Cost-Charged": "credits charged for this response (0 on every wall)",
      "X-Cost-Remaining": "credits remaining after this response; 'unknown' means not replicated yet, never unlimited",
      "X-RateLimit-Limit": "requests allowed in the current window",
      "X-RateLimit-Remaining": "requests left in the current window",
      "X-RateLimit-Reset": "unix time the window resets"
    },
    "body": {
      "passthrough": "the supplier's document, verbatim, except the two changes below",
      "additions": {
        "meta.licence": "licence block copied from the product catalogue: id, provider, attribution_required, attribution_text — everything needed to attribute the data is in the response that carried it",
        "meta.location": "echo of the lat/lon the call resolved",
        "meta.timezone / meta.timezone_offset": "the feed's timezone fields, when the feed supplies them"
      },
      "rewrites": {
        "prev / next": "origin pagination links are replaced by prev_cursor / next_cursor — opaque sealed cursors; the origin's own links (which can embed credentials) never reach the client"
      }
    },
    "sample": {
      "route": "/onecall3/forecast?lat=51.5074&lon=-0.1278",
      "body": {
        "lat": 51.5074,
        "lon": -0.1278,
        "timezone": "Europe/London",
        "timezone_offset": 3600,
        "current": {
          "temp": 290.43,
          "humidity": 68,
          "weather": [
            {
              "main": "Clouds"
            }
          ]
        },
        "daily": [
          {
            "summary": "Expect a day of partly cloudy with rain"
          }
        ],
        "meta": {
          "licence": {
            "id": "ODbL-1.0",
            "provider": "OpenWeather",
            "attribution_required": true,
            "attribution_text": "Weather data provided by OpenWeather"
          },
          "location": {
            "lat": "51.5074",
            "lon": "-0.1278"
          }
        }
      },
      "note": "abridged: the live document carries current, minutely, hourly, daily and alerts in full"
    }
  },
  "billing": {
    "unit": "call",
    "credits_per_unit": 1,
    "rule": "only successful (2xx) data responses are billed; upstream failures cost nothing and answer upstream_error",
    "price_authority": "https://api.forum.bot/v1/products"
  },
  "errors": "every error is an envelope from the closed dictionary at https://forum.bot/errors.json — branch on code, never on prose",
  "licence": {
    "id": "ODbL-1.0",
    "provider": "OpenWeather",
    "attribution_required": true,
    "attribution_text": "Weather data provided by OpenWeather"
  },
  "links": {
    "products": "https://api.forum.bot/v1/products",
    "guide": "https://forum.bot/guide.md",
    "quickstart": "https://forum.bot/llms.txt",
    "openapi": "https://api.forum.bot/openapi.json",
    "terms": "https://forum.bot/tos/last.json"
  }
}