api.invoket.com

{
  "properties": {
    "data": {
      "properties": {
        "count": {
          "description": "Number of results returned, equal to the number of queries submitted (capped at 500)",
          "type": "integer"
        },
        "results": {
          "description": "One result per input query, in the same order. An item outside the forecast window, off-grid, or with an unknown/ambiguous city returns coverage.complete=false (partial success) rather than failing the batch; the call fails (400) only when zero items are covered. City items echo the resolved place as location. Per item, lead.step_offset_secs (signed seconds, step_time minus valid_time, present only when non-zero) reports how far the served model step sits from the instant asked for; values are never interpolated between steps.",
          "items": {
            "properties": {
              "coverage": {
                "properties": {
                  "complete": {
                    "type": "boolean"
                  },
                  "reason": {
                    "description": "Why this item is degraded, present when its 'complete' is false: outside the forecast window, off-grid, or an unknown/ambiguous city. The item then carries only its echo — no value is invented and the batch does not fail",
                    "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": {
                "type": "integer"
              },
              "lat": {
                "type": "number"
              },
              "lead": {
                "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": {
                "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": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                "required": [
                  "total_mm"
                ],
                "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"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "count",
        "results"
      ],
      "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": {
          "type": "string"
        }
      },
      "required": [
        "dataset",
        "fetched_at",
        "freshness",
        "source"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "provenance"
  ],
  "type": "object"
}