api.invoket.com

{
  "properties": {
    "data": {
      "properties": {
        "coverage": {
          "properties": {
            "complete": {
              "type": "boolean"
            },
            "reason": {
              "description": "Why the series is incomplete, present when 'complete' is false — a partial day or a grid cell without data; per-day detail sits in data.days[].coverage",
              "type": "string"
            }
          },
          "required": [
            "complete"
          ],
          "type": "object"
        },
        "days": {
          "description": "One entry per UTC calendar day, in date order: daily min/max temperature, total precipitation, max wind, the model that served it and how many forecast steps fed it",
          "items": {
            "properties": {
              "coverage": {
                "description": "Per-day coverage: complete=false for partial days (day 0 from the cycle hour, the truncated last day of the window) or a grid cell with no data, values then null and never invented",
                "properties": {
                  "complete": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "complete"
                ],
                "type": "object"
              },
              "dataset": {
                "description": "Stable machine identifier of the model that served this day: gfs or gefs. Makes the deterministic/ensemble boundary readable day by day without parsing the label in data.days[].source.",
                "type": "string"
              },
              "date": {
                "type": "string"
              },
              "precipitation_sum_mm": {
                "description": "Daily total precipitation (mm), reconstructed from the model's disjoint accumulation buckets (0-3 h, 0-6 h, 6-9 h ...) — never a naive sum of overlapping buckets. On days served by the GEFS ensemble mean (dataset=gefs, beyond ~16 days) it is an average over ~30 members: averaging spreads rain across them, so heavy-rain days AND fully dry days are largely absent — measured at Paris on 2026-07-25, the 19-day ensemble tail stayed within 0.4-1.8 mm/day while the deterministic days ranged 0.0-13.1 mm/day. Use those days for trend, never for a threshold trigger (a 'more than 30 mm in a day' or 'dry day' rule will essentially never fire); the deterministic GFS days are the ones that resolve extremes.",
                "type": [
                  "number",
                  "null"
                ]
              },
              "source": {
                "description": "Human-readable label of the model that served this day: 'GFS' (deterministic 0.25 deg, <= 384 h); 'NOAA GEFS ensemble mean (35-day, 0.5 deg)' beyond, when that window is served — an ensemble-mean day averages ~30 members, so its extremes are smoothed (see data.days[].precipitation_sum_mm). Its wording is not part of the contract — branch on data.days[].dataset instead.",
                "type": "string"
              },
              "steps_used": {
                "type": "integer"
              },
              "temperature_max_c": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "temperature_min_c": {
                "description": "Daily minimum 2 m temperature (deg C), derived from the 3-hourly forecast steps (subsampled; native GRIB TMIN/TMAX fields are roadmap). Same for temperature_max_c. On days served by the GEFS ensemble mean (dataset=gefs, beyond ~16 days) both are averages over ~30 members and the daily range collapses towards the climatological average — measured at Paris on 2026-07-25, the max spanned 25.3-27.9 deg C over the 19-day tail against 21.2-40.5 deg C on the deterministic days: trend, not threshold triggers.",
                "type": [
                  "number",
                  "null"
                ]
              },
              "wind_speed_max_ms": {
                "description": "Peak 10 m wind speed over the day (m/s), max of the 3-hourly forecast steps. On days served by the GEFS ensemble mean (dataset=gefs, beyond ~16 days) it is an average over ~30 members: gusty peaks are smoothed away — trend, not threshold triggers.",
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "coverage",
              "dataset",
              "date",
              "source",
              "steps_used"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "from": {
          "type": "string"
        },
        "grid": {
          "properties": {
            "distance_km": {
              "type": "number"
            },
            "lat": {
              "type": "number"
            },
            "lon": {
              "type": "number"
            }
          },
          "required": [
            "distance_km",
            "lat",
            "lon"
          ],
          "type": "object"
        },
        "lat": {
          "type": "number"
        },
        "lead": {
          "properties": {
            "cycle": {
              "type": "string"
            }
          },
          "required": [
            "cycle"
          ],
          "type": "object"
        },
        "location": {
          "description": "Echo of the resolved place when city=/location= was used — name, ISO country, admin1 code and the exact GeoNames coordinates the series was served at; absent when lat/lon were passed directly",
          "type": "object"
        },
        "lon": {
          "type": "number"
        },
        "to": {
          "type": "string"
        }
      },
      "required": [
        "coverage",
        "days",
        "from",
        "lat",
        "lead",
        "lon",
        "to"
      ],
      "type": "object"
    },
    "provenance": {
      "properties": {
        "dataset": {
          "description": "Stable machine identifier of the model(s) that served the series: gfs, gefs, or gfs+gefs when the range spans both (the per-day boundary is readable in data.days[].dataset). Branch on this field rather than parsing provenance.source, which joins the human-readable labels.",
          "type": "string"
        },
        "fetched_at": {
          "type": "string"
        },
        "freshness": {
          "properties": {
            "kind": {
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        "source": {
          "type": "string"
        }
      },
      "required": [
        "dataset",
        "fetched_at",
        "freshness",
        "source"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "provenance"
  ],
  "type": "object"
}