api.invoket.com

{
  "properties": {
    "data": {
      "properties": {
        "clouds": {
          "properties": {
            "total_cover_pct": {
              "description": "Total (whole-column) cloud cover in percent; null when unavailable at the grid cell",
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "total_cover_pct"
          ],
          "type": "object"
        },
        "convective": {
          "properties": {
            "cape_jkg": {
              "description": "Surface-based Convective Available Potential Energy in J/kg (raw GFS value); null when unavailable at the grid cell or beyond the deterministic window",
              "type": [
                "number",
                "null"
              ]
            },
            "cin_jkg": {
              "description": "Convective Inhibition in J/kg (raw, negative or zero); a strong cap suppresses convection despite high CAPE. Secondary: null CIN alone does not degrade coverage",
              "type": [
                "number",
                "null"
              ]
            },
            "inhibited": {
              "description": "True when CIN <= -100 J/kg (a strong cap likely to suppress convection despite instability); reported separately, it never changes the risk category. null when CIN is unavailable",
              "type": [
                "boolean",
                "null"
              ]
            },
            "risk": {
              "description": "Qualitative instability proxy derived from surface CAPE — an instability/thunderstorm-hail-risk proxy, NOT a calibrated hail probability (hail also needs shear, freezing level…). Scale (NWS/SPC conventions, J/kg): none [<100), low [100,1000), moderate [1000,2500), high [2500,4000), extreme [>=4000). null when CAPE is unavailable",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "cape_jkg",
            "cin_jkg",
            "inhibited",
            "risk"
          ],
          "type": "object"
        },
        "coverage": {
          "properties": {
            "complete": {
              "type": "boolean"
            },
            "reason": {
              "description": "Which requested family could not be served for this point and step, present when 'complete' is false — the block is then served with null values rather than extrapolated",
              "type": "string"
            }
          },
          "required": [
            "complete"
          ],
          "type": "object"
        },
        "date": {
          "type": "string"
        },
        "grid": {
          "properties": {
            "distance_km": {
              "type": "number"
            },
            "lat": {
              "type": "number"
            },
            "lon": {
              "type": "number"
            }
          },
          "required": [
            "distance_km",
            "lat",
            "lon"
          ],
          "type": "object"
        },
        "horizon_h": {
          "description": "Echo of the requested lead time in hours, always counted from the deterministic GFS cycle. Beyond 384 h the answer comes from the GEFS 00Z cycle, structurally one cycle behind, so lead.horizon_h counts more hours from that cycle for the same instant: compare lead.valid_time, not the two horizon counts.",
          "type": "integer"
        },
        "humidity": {
          "properties": {
            "relative_pct": {
              "description": "2 m relative humidity in percent; null when unavailable at the grid cell",
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "relative_pct"
          ],
          "type": "object"
        },
        "lat": {
          "type": "number"
        },
        "lead": {
          "description": "Resolved lead: analysis cycle, requested instant, lead hours, and the exact forecast step served; clamped=true when horizon_h was reduced to the latest available step. horizon_h here is recounted from the cycle that served the data (see data.horizon_h). step_offset_secs (signed seconds, step_time minus valid_time, present only when non-zero) is how far the served step sits from the instant asked for: a step covers the interval that follows it, so an unaligned instant is served by the preceding step — up to 4 h on the 6-hourly GEFS tail. Never interpolated between steps; coverage.reason spells the gap out and coverage.complete stays true.",
          "properties": {
            "clamped": {
              "type": "boolean"
            },
            "cycle": {
              "type": "string"
            },
            "horizon_h": {
              "type": "integer"
            },
            "step_offset_secs": {
              "type": "integer"
            },
            "step_time": {
              "type": "string"
            },
            "valid_time": {
              "type": "string"
            }
          },
          "required": [
            "cycle",
            "horizon_h",
            "valid_time"
          ],
          "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 lookup was served at",
          "properties": {
            "admin1": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "lat": {
              "type": "number"
            },
            "lon": {
              "type": "number"
            },
            "name": {
              "type": "string"
            },
            "source": {
              "type": "string"
            }
          },
          "required": [
            "admin1",
            "country",
            "lat",
            "lon",
            "name",
            "source"
          ],
          "type": "object"
        },
        "lon": {
          "type": "number"
        },
        "precipitation": {
          "properties": {
            "total_mm": {
              "description": "Forecast precipitation for the served step (mm). Beyond 384 h (dataset=gefs) every value served — this one, temperature and wind alike — is a ~30-member ensemble mean: averaging spreads rain across members, so heavy-rain steps and dry steps are largely absent (tail measured 0.4-1.8 mm/day vs 0.0-13.1 on the deterministic segment). Never build a threshold trigger on that range; dataset=gfs is the segment that resolves extremes.",
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "total_mm"
          ],
          "type": "object"
        },
        "snow": {
          "properties": {
            "depth_m": {
              "description": "Snow depth on the ground in metres (state, SNOD); distinct from is_snow. null when unavailable at the grid cell",
              "type": [
                "number",
                "null"
              ]
            },
            "is_snow": {
              "description": "Whether precipitation at the served step is falling as snow (GFS categorical CSNOW); distinct from depth_m. null when unavailable at the grid cell",
              "type": [
                "boolean",
                "null"
              ]
            }
          },
          "required": [
            "depth_m",
            "is_snow"
          ],
          "type": "object"
        },
        "temperature": {
          "properties": {
            "celsius": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "celsius"
          ],
          "type": "object"
        },
        "valid_time": {
          "type": "string"
        },
        "wind": {
          "properties": {
            "direction_deg": {
              "type": [
                "number",
                "null"
              ]
            },
            "speed_ms": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "direction_deg",
            "speed_ms"
          ],
          "type": "object"
        }
      },
      "required": [
        "coverage",
        "grid",
        "lat",
        "lead",
        "lon"
      ],
      "type": "object"
    },
    "provenance": {
      "properties": {
        "dataset": {
          "description": "Stable machine identifier of the model that served the response, one of: gfs (deterministic NOAA GFS 0.25 deg, <= 384 h), gefs (NOAA GEFS ensemble mean 0.5 deg, beyond 384 h). Branch on this field rather than parsing provenance.source, which carries the human-readable label (the GEFS label spells out that it is an ensemble mean) whose wording is not part of the contract.",
          "type": "string"
        },
        "fetched_at": {
          "type": "string"
        },
        "freshness": {
          "properties": {
            "kind": {
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        "source": {
          "description": "Human-readable label of the model that served the response: 'GFS' (deterministic, 0.25 deg, <= 384 h) or 'NOAA GEFS ensemble mean (35-day, 0.5 deg)' beyond — the label spells out that the long-range answer is an ensemble mean, not a deterministic scenario. Written for humans, its exact wording is not part of the contract: branch on provenance.dataset.",
          "type": "string"
        }
      },
      "required": [
        "dataset",
        "fetched_at",
        "freshness",
        "source"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "provenance"
  ],
  "type": "object"
}