Input schema (JSON)
{
"type": "object",
"required": [
"dataset",
"request"
],
"properties": {
"accept": {
"enum": [
"text/csv",
"application/json",
"application/ndjson",
"application/x-ndjson",
"application/vnd.apache.parquet",
"application/x-parquet",
"application/parquet"
],
"type": "string",
"description": "Desired response format. Defaults to text/csv for compatibility. For dense grids and large tabular analysis, use application/vnd.apache.parquet only when a compatible reader is already known to be available. If reader availability is unknown, do not probe or install packages; use text/csv with delivery=url immediately."
},
"dataset": {
"type": "string",
"description": "Dataset code, for example gfs, ifsoper, nbm, hrrr, or urma."
},
"request": {
"type": "object",
"properties": {
"asOf": {
"type": "string",
"description": "Do not set asOf unless the user explicitly asks for backtesting, time travel, what was known then, or a historical model-run cutoff. Omit asOf for latest or best-available forecasts because it filters out forecast runs newer than the cutoff and can make recent data look missing. This is a UTC model-run-time cutoff for /timeseries, not a live API availability timestamp."
},
"grid": {
"type": "object",
"required": [
"minLatitude",
"maxLatitude",
"minLongitude",
"maxLongitude",
"step"
],
"properties": {
"step": {
"type": "number",
"description": "Requested sampling step in degrees, greater than 0. Finer sampling does not increase forecast resolution. Native latitude and longitude steps can differ; projected and unstructured grids have no single degree step."
},
"maxLatitude": {
"type": "number"
},
"minLatitude": {
"type": "number"
},
"maxLongitude": {
"type": "number"
},
"minLongitude": {
"type": "number"
}
},
"description": "Optional regular latitude/longitude grid. Use this instead of or in addition to coordinates. The API preserves the requested step and does not silently coarsen fine grids. The default limit is 120000 expanded coordinates; account-specific plan or token settings may set a different maximum up to 1050000, enough for a full native 0.25-degree global GFS grid, and an oversized-response error reports the applicable maximum. Use URL delivery for dense grids before considering spatial tiling.",
"additionalProperties": false
},
"filter": {
"type": "object",
"properties": {
"alias": {
"type": "string",
"description": "Output field name for the expression."
},
"hidden": {
"type": "boolean",
"description": "Optional: hide this expression from the response output."
},
"expression": {
"type": "string",
"description": "Expression text. Reference variable aliases, not raw selector names."
}
},
"description": "Optional row filter expression evaluated from variable aliases.",
"additionalProperties": true
},
"members": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Optional ensemble member numbers."
},
"fromTime": {
"type": "string",
"description": "Inclusive UTC valid-time range start for /timeseries, for example 2025-05-01T00:00:00Z. Must be earlier than untilTime; use timesList for one exact valid time."
},
"timesList": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact UTC valid times for /timeseries, or exact UTC model run times for /runs. Use this for one exact time instead of setting range bounds equal."
},
"untilTime": {
"type": "string",
"description": "Exclusive UTC valid-time range end for /timeseries, for example 2025-05-01T06:00:00Z. Must be later than fromTime; equal bounds select no times."
},
"variables": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"level",
"info"
],
"properties": {
"info": {
"type": "string",
"description": "Exact info string. Use an empty string when the catalog selector has no info value."
},
"name": {
"type": "string",
"description": "Exact case-sensitive parameter short name, for example TMP."
},
"alias": {
"type": "string",
"description": "Optional response field name. Strongly recommended."
},
"level": {
"type": "string",
"description": "Exact level string, for example 2 m above ground."
},
"hidden": {
"type": "boolean",
"description": "Optional: hide intermediate variables used only by expressions."
}
},
"additionalProperties": false
},
"description": "Variable selectors. This exact field name is required. Do not use parameters, parameter, variable, selector, or selectors. Values must be exact case-sensitive selector tuples discovered from catalog tools."
},
"maxHorizon": {
"type": "integer",
"description": "Optional maximum lead time in hours."
},
"minHorizon": {
"type": "integer",
"description": "Optional minimum lead time in hours."
},
"coordinates": {
"type": "array",
"items": {
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"description": "Longitude in decimal degrees."
},
"name": {
"type": "string",
"description": "Optional coordinate label copied into the response."
}
},
"additionalProperties": false
},
"description": "Point coordinates. This exact field name is required. Do not use location, coord, coords, latitude/longitude at top level, or any singular replacement."
},
"expressions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"alias": {
"type": "string",
"description": "Output field name for the expression."
},
"hidden": {
"type": "boolean",
"description": "Optional: hide this expression from the response output."
},
"expression": {
"type": "string",
"description": "Expression text. Reference variable aliases, not raw selector names."
}
},
"description": "Expression object.",
"additionalProperties": true
},
"description": "Optional derived variables evaluated from variable aliases."
},
"forecastedFrom": {
"type": "string",
"description": "Inclusive UTC model-run-time range start for /runs. Must be earlier than forecastedUntil; use timesList for one exact model run time."
},
"forecastedUntil": {
"type": "string",
"description": "Exclusive UTC model-run-time range end for /runs. Must be later than forecastedFrom; equal bounds select no times."
},
"includeMetadata": {
"type": "array",
"items": {
"enum": [
"index_updated_at",
"native_coordinate"
],
"type": "string"
},
"description": "Optional additional row metadata: native_coordinate adds native_lat/native_lon for mapping requested sampling onto source cells; index_updated_at adds index freshness. Do not request forecasted_at or forecasted_time here; both are regular response columns returned automatically."
}
},
"description": "Timeseries request body. Use timesList for exact UTC valid times, or the half-open range fromTime+untilTime where fromTime is inclusive, untilTime is exclusive, and fromTime must be earlier than untilTime. Equal bounds select no times. Omit asOf unless the user explicitly asks for backtesting, time travel, what was known then, or a historical model-run cutoff. Coordinates must be in request.coordinates, and variable selectors must be in request.variables.",
"additionalProperties": true
},
"delivery": {
"enum": [
"inline",
"url"
],
"type": "string",
"description": "Optional result delivery mode. Set inline for CSV, JSON, or NDJSON in the MCP result, or url for a short-lived signed resource link. Omission defaults to inline for text formats; Parquet always uses URL delivery and rejects delivery=inline. For a resource_link blocked by client network policy, do not retry URL delivery: if a text artifact is at most 10000000 bytes, retry the same request at most once with delivery=inline; otherwise reduce it using the documented split order first."
},
"max_bytes": {
"type": "integer",
"maximum": 10000000,
"minimum": 1,
"description": "Maximum inline response bytes to return through MCP for CSV/JSON/NDJSON. Default and server-side maximum are 10000000. This setting does not limit artifacts delivered by signed URL. For dense grids or large tabular results, use delivery=url so MCP returns a short-lived signed HTTPS resource link instead of putting the full dataset into tool output. Prefer application/vnd.apache.parquet only when a compatible Parquet reader is already known to be available. If reader availability is unknown, do not spend tool calls probing or installing packages; use text/csv with delivery=url immediately. Use one grid request, process the downloaded file locally, and never print or serialize the full file into chat or tool output. Do not install a dependency or write a Parquet parser solely for one result. When a real API request limit requires splitting, split by time range first, split variables second, and split coordinates/grid/space last; spatial tiling creates the most extra work."
}
},
"additionalProperties": false
}