TimeseriesPostRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gribstream-com/json-schema/gribstream-com-timeseries-post-request-schema.json",
  "title": "TimeseriesPostRequest",
  "description": "Best-available-timeseries request.\n\nProvide:\n- `fromTime` + `untilTime`, or `timesList`\n- `coordinates` or `grid`\n- at least one `variables` entry\n\nAll timestamps are UTC.\n\n`fromTime`, `untilTime`, and `timesList` refer to valid times to retrieve.\n`asOf` is a UTC model-run-time cutoff: runs newer than that timestamp are excluded. It is not a guarantee of the wall-clock time when GribStream first indexed or exposed the run through the live API. If you need to approximate live availability, subtract a conservative dataset/horizon-specific provider publication lag before using a historical decision time as `asOf`.\n\nVariable selectors are exact dataset-defined tuples. Discover them from\n`GET /api/v2/catalog/datasets/{dataset}/parameters/{parameter}` or copy them exactly from\nthe dataset inventory/model pages.\n\nPrefer `minLeadTime` / `maxLeadTime` over deprecated integer horizons, especially for\nminute-based datasets such as `hrrrsubh` and `rtmaru`.\n\nSet `includeMetadata` to `[\"index_updated_at\"]` to include the latest ClickHouse\nindex timestamp among the selected GRIB index rows used for each result row.\nSet it to `[\"native_coordinate\"]` to include the fixed grid cell center selected\nfor each requested coordinate; use both values to include both kinds of metadata.\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gribstream-com-openapi.yml#/components/schemas/TimeseriesPostRequest",
  "type": "object",
  "properties": {
    "fromTime": {
      "type": "string",
      "format": "date-time",
      "description": "Inclusive UTC valid-time lower bound."
    },
    "untilTime": {
      "type": "string",
      "format": "date-time",
      "description": "Inclusive UTC valid-time upper bound."
    },
    "timesList": {
      "type": "array",
      "description": "Exact UTC valid times to retrieve.",
      "items": {
        "type": "string",
        "format": "date-time"
      }
    },
    "asOf": {
      "type": "string",
      "format": "date-time",
      "description": "Exclude model runs whose run time is newer than this UTC timestamp. Defaults to current UTC time; it is not a live API availability timestamp."
    },
    "minLeadTime": {
      "type": "string",
      "description": "Minimum lead time duration, such as `45m` or `18h`."
    },
    "maxLeadTime": {
      "type": "string",
      "description": "Maximum lead time duration, such as `45m` or `18h`."
    },
    "minHorizon": {
      "type": "integer",
      "format": "int64",
      "deprecated": true,
      "description": "Deprecated integer-hour lead time."
    },
    "maxHorizon": {
      "type": "integer",
      "format": "int64",
      "deprecated": true,
      "description": "Deprecated integer-hour lead time."
    },
    "coordinates": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Coordinate"
      }
    },
    "grid": {
      "$ref": "#/$defs/GridBounds"
    },
    "variables": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/VariableSelector"
      }
    },
    "expressions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ExpressionField"
      }
    },
    "filter": {
      "$ref": "#/$defs/FilterExpression"
    },
    "members": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Ensemble member numbers. Deterministic datasets reject this field with `400 Bad Request`. If omitted on an ensemble dataset, only the first member is returned."
    },
    "includeMetadata": {
      "type": "array",
      "description": "Optional metadata fields to include in data rows.",
      "items": {
        "type": "string",
        "enum": [
          "index_updated_at",
          "native_coordinate"
        ]
      }
    }
  },
  "required": [
    "variables"
  ],
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "coordinates"
          ]
        },
        {
          "required": [
            "grid"
          ]
        }
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "fromTime",
            "untilTime"
          ]
        },
        {
          "required": [
            "timesList"
          ]
        }
      ]
    }
  ],
  "$defs": {
    "Coordinate": {
      "type": "object",
      "required": [
        "lat",
        "lon"
      ],
      "properties": {
        "lat": {
          "type": "number",
          "format": "double",
          "description": "Latitude in degrees."
        },
        "lon": {
          "type": "number",
          "format": "double",
          "description": "Longitude in degrees."
        },
        "name": {
          "type": "string",
          "description": "Optional label copied into result rows."
        }
      },
      "additionalProperties": false
    },
    "ExpressionField": {
      "type": "object",
      "required": [
        "expression"
      ],
      "properties": {
        "expression": {
          "type": "string",
          "description": "Expr-language formula compiled by the server."
        },
        "alias": {
          "type": "string",
          "description": "Response key for the expression output.\n\nThe wire format allows this to be omitted, but practical clients should set it.\n"
        },
        "hidden": {
          "type": "boolean",
          "description": "When `true`, the expression result remains available to later expressions and filters,\nbut is omitted from response rows.\n"
        }
      },
      "additionalProperties": false
    },
    "FilterExpression": {
      "type": "object",
      "required": [
        "expression"
      ],
      "properties": {
        "expression": {
          "type": "string",
          "description": "Expr-language boolean filter. Rows are kept only when it evaluates to `true`."
        }
      },
      "additionalProperties": false
    },
    "GridBounds": {
      "type": "object",
      "required": [
        "minLatitude",
        "maxLatitude",
        "minLongitude",
        "maxLongitude",
        "step"
      ],
      "description": "Bounding box used to expand into a coordinate grid.\n\nThe API preserves the requested `step`; it does not silently coarsen fine grids.\nExpanded grids are limited to 120,000 coordinates by default. Account-specific plan\nor token limits may set a different maximum, up to 1,050,000 coordinates. This ceiling\naccommodates a full native 0.25-degree global GFS grid. Oversized grids return `400`\nwith the applicable maximum in the response.\n\nFor dense grids and large tabular responses, request `application/vnd.apache.parquet`.\nParquet avoids the transfer overhead of textual formats, while the service reduces\nlarge-grid worker fan-out to keep extraction memory bounded.\n",
      "properties": {
        "minLatitude": {
          "type": "number",
          "format": "double"
        },
        "maxLatitude": {
          "type": "number",
          "format": "double"
        },
        "minLongitude": {
          "type": "number",
          "format": "double"
        },
        "maxLongitude": {
          "type": "number",
          "format": "double"
        },
        "step": {
          "type": "number",
          "format": "double",
          "description": "Grid spacing in degrees. Must be greater than 0."
        }
      },
      "additionalProperties": false
    },
    "VariableSelector": {
      "type": "object",
      "description": "Exact dataset selector tuple used in forecast queries.\n\nSelectors are not free-form. `name`, `level`, and optional `info` must exactly match a\nselector published for the chosen dataset, either from the dataset catalog endpoints or the\ndataset model/inventory page. Do not invent selectors from natural-language descriptions.\n",
      "required": [
        "name",
        "level"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "GRIB short name exactly as exposed by the dataset inventory or catalog. Case-sensitive. Examples include `TMP`, `UGRD`, `APCP`, `100u`, and `2t`."
        },
        "level": {
          "type": "string",
          "description": "Level text exactly as exposed by the dataset inventory or catalog variation. Must match the published selector tuple exactly."
        },
        "info": {
          "type": "string",
          "description": "Optional extra qualifier from the published selector tuple. Blank string is common. Do not invent natural-language qualifiers here."
        },
        "alias": {
          "type": "string",
          "description": "Optional response key.\n\nIf omitted, the current handlers emit the column as `NAME|LEVEL|INFO`.\n"
        },
        "hidden": {
          "type": "boolean",
          "description": "When `true`, the field is loaded and remains available to expressions and filters,\nbut is omitted from response rows. Shared-parameter derived requests use this for\nintermediate helper inputs such as wind vector components.\n"
        }
      },
      "additionalProperties": false
    }
  }
}