Weather Forecast API Documentation

This API provides access to weather forecast data for all models. You can retrieve historical and forecasted weather data by specifying parameters such as time range, coordinates, and variables of interest.

You can use our python client at GitHub or roll your own with the details below.

Weather History Endpoint

For any given coordinate, weather parameter, and time range, there are multiple forecasted values available. Each value corresponds to a different forecast horizon (lead time), representing predictions made at various times in the past.

The API returns the forecasted value with the shortest forecast horizon for each time point. This means you receive the most recent and presumably most accurate prediction available at that moment. In data science, this is often referred to as the "best" forecast or the "nowcast" series.

POST https://gribstream.com/api/v2/<model>/history

Available Models

rap - Rapid Refresh (RAP)
gfs - Global Forecast System (GFS)
nbm - National Blend of Models (NBM)
hrrr - High-Resolution Rapid Refresh (HRRR)
graphcast - GraphCast Global Forecast System (GraphCast GFS)
gefsatmosmean - Global Ensemble Forecast System (Wave Prob GEFS)
gefschem - Global Ensemble Forecast System (Chem GEFS)
gefswaveprob - Global Ensemble Forecast System (Wave Prob GEFS)
cfsflxf - Climate Forecast System (Radiative Fluxes CFS)
cfspgbf - Climate Forecast System (Pressure Level CFS)
cfsipvf - Climate Forecast System (Isentropic Level CFS)
cfsocnf - Climate Forecast System (Ocean CFS)

Request Headers

Header	Value	Comment
`Content-Type`	`application/json`	Default and only valid value.
`Accept`	Choose `text/csv`, `application/json` or `application/ndjson`	Selects the response format. Defaults to `text/csv`
`Accept-Encoding`	`gzip`	Optional, recommended, for compressed response
`Authorization`	`Bearer <token>`	Replace <token> with your authentication token

Request Body Parameters

The request body should be a JSON object with the following structure:

Parameter	Type	Description	Required
`fromTime`	`string` (ISO 8601)	Start time of the forecast period.	Yes, either (fromTime, untilTime) or timesList
`untilTime`	`string` (ISO 8601)	End time of the forecast period.	Yes, either (fromTime, untilTime) or timesList
`timesList`	`array` of string (ISO 8601)	Array of forecasted times.	Yes, either (fromTime, untilTime) or timesList
`asOf`	`string` (ISO 8601)	Reference time for the forecast data.	No
`minHorizon`	`integer`	Minimum forecast horizon in hours.	No (default: 0)
`maxHorizon`	`integer`	Maximum forecast horizon in hours.	No (default: 384)
`coordinates`	`array` of coordinate objects	List of geographical coordinates.	Yes
`variables`	`array` of variable objects	List of weather variables to retrieve.	Yes
`expressions`	`array` of expression objects	Server‑side calculated columns built from the variables you request. Each entry returns as its own column, using the supplied alias.	No

NOTE: Selected time must be specified via range (fromTime, untilTime) or timesList

Coordinate Object

Field	Type	Description	Required
`lat`	`float`	Latitude of the coordinate.	Yes
`lon`	`float`	Longitude of the coordinate.	Yes
`name`	`string`	Optional name for the coordinate, which will be returned in the response to help identify the location.	No

Variable Object

Check the full list of available parameters per model.

Field	Type	Description	Required
`name`	`string`	Name of the weather variable (e.g., `"TMP"` for temperature).	Yes
`level`	`string`	Level of the atmosphere or surface (e.g., `"2 m above ground"`).	Yes
`info`	`string`	Differentiator when the model has multiple parameters for the same name and level	No
`alias`	`string`	Optional alias for the variable. If provided, this alias will be used as the column header in the response.	No

Expression Object

Field	Type	Description	Required
`expression`	`string`	Go‑template expression evaluated per‑row. • All selected variables are addressable by their alias (or default column name). • Math operators `+ ‑ * / %` and functions in `func.` (`Abs`, `Atan2`, `Hypot`, `Pow`, `Sqrt`, etc.) are allowed.	Yes
`alias`	`string`	Column name used in the response for this calculated result.	Yes

Example Request

POST https://gribstream.com/api/v2/hrrr/history
Content-Type: application/json
Accept-Encoding: gzip
Authorization: Bearer <token>
Payload:
{
    "fromTime": "2024-09-10T00:00:00Z",
    "untilTime": "2024-09-10T10:00:00Z",
    "asOf": "2024-09-10T05:00:00Z",
    "minHorizon": 1,
    "maxHorizon": 48,
    "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
    "variables": [
        { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
        { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
    ],
    "expressions": [
        { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
        { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
    ]
}

Example Response

The format of the response is determined by the Accept header. The API supports three response formats:

Accept: text/csv - the response is a CSV file containing the forecast data.
Accept: application/json - each line in the response is a separate JSON object.
Accept: application/ndjson - the response is a single JSON array of objects.

If the Accept-Encoding: gzip header is included, the response will be gzip-compressed.

NOTE: The response is not strictly in-order.

CSV Response Example

forecasted_at,forecasted_time,lat,lon,name,uwind,vwind,wind_direction,wind_magnitude
2024-09-10T02:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.1213,1.7680,256,7.3375
2024-09-10T05:00:00Z,2024-09-10T08:00:00Z,40.7306,-73.9352,New York City,5.2585,-1.1512,282,5.3831
2024-09-10T01:00:00Z,2024-09-10T02:00:00Z,40.7306,-73.9352,New York City,8.1815,1.6363,258,8.3435
2024-09-10T05:00:00Z,2024-09-10T07:00:00Z,40.7306,-73.9352,New York City,6.9156,-1.4414,281,7.0642
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,40.7306,-73.9352,New York City,8.0572,2.9389,249,8.5765
2024-09-10T03:00:00Z,2024-09-10T04:00:00Z,40.7306,-73.9352,New York City,6.4841,2.5385,248,6.9633
2024-09-10T05:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.8368,0.1001,269,6.8375
2024-09-10T04:00:00Z,2024-09-10T05:00:00Z,40.7306,-73.9352,New York City,6.4087,3.0921,244,7.1157
2024-09-09T23:00:00Z,2024-09-10T00:00:00Z,40.7306,-73.9352,New York City,6.1795,3.9539,237,7.3362
2024-09-10T05:00:00Z,2024-09-10T09:00:00Z,40.7306,-73.9352,New York City,4.7715,-0.5644,276,4.8047

JSON Response Example (JSON Array)

[{"forecasted_at":"2024-09-10T02:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.121286392211914,"vwind":1.7680130004882812,"wind_direction":256,"wind_magnitude":7.337478439477567}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T01:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.057228088378906,"vwind":2.938892364501953,"wind_direction":249,"wind_magnitude":8.576480210336284}
,{"forecasted_at":"2024-09-10T01:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.181510925292969,"vwind":1.6362571716308594,"wind_direction":258,"wind_magnitude":8.34352794400556}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T06:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.836750030517578,"vwind":0.10012435913085938,"wind_direction":269,"wind_magnitude":6.837483152964509}
,{"forecasted_at":"2024-09-09T23:00:00Z","forecasted_time":"2024-09-10T00:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.179473876953125,"vwind":3.953920364379883,"wind_direction":237,"wind_magnitude":7.33616954846356}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.915561676025391,"vwind":-1.4414329528808594,"wind_direction":281,"wind_magnitude":7.064185887458082}
,{"forecasted_at":"2024-09-10T03:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.484088897705078,"vwind":2.538473129272461,"wind_direction":248,"wind_magnitude":6.963279016482147}
,{"forecasted_at":"2024-09-10T04:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.408748626708984,"vwind":3.0920562744140625,"wind_direction":244,"wind_magnitude":7.115677828885149}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":5.258523941040039,"vwind":-1.1512451171875,"wind_direction":282,"wind_magnitude":5.383069696589422}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.771465301513672,"vwind":-0.564422607421875,"wind_direction":276,"wind_magnitude":4.804732459078015}
]

NDJSON Response Example (Line-delimited)

{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.915561676025391,"vwind":-1.4414329528808594,"wind_direction":281,"wind_magnitude":7.064185887458082}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":5.258523941040039,"vwind":-1.1512451171875,"wind_direction":282,"wind_magnitude":5.383069696589422}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.771465301513672,"vwind":-0.564422607421875,"wind_direction":276,"wind_magnitude":4.804732459078015}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T06:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.836750030517578,"vwind":0.10012435913085938,"wind_direction":269,"wind_magnitude":6.837483152964509}
{"forecasted_at":"2024-09-10T03:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.484088897705078,"vwind":2.538473129272461,"wind_direction":248,"wind_magnitude":6.963279016482147}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T01:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.057228088378906,"vwind":2.938892364501953,"wind_direction":249,"wind_magnitude":8.576480210336284}
{"forecasted_at":"2024-09-09T23:00:00Z","forecasted_time":"2024-09-10T00:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.179473876953125,"vwind":3.953920364379883,"wind_direction":237,"wind_magnitude":7.33616954846356}
{"forecasted_at":"2024-09-10T01:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.181510925292969,"vwind":1.6362571716308594,"wind_direction":258,"wind_magnitude":8.34352794400556}
{"forecasted_at":"2024-09-10T04:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.408748626708984,"vwind":3.0920562744140625,"wind_direction":244,"wind_magnitude":7.115677828885149}
{"forecasted_at":"2024-09-10T02:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.121286392211914,"vwind":1.7680130004882812,"wind_direction":256,"wind_magnitude":7.337478439477567}

Response Fields:

Field	Description
`forecasted_at`	The time when the forecast was generated.
`forecasted_time`	The time for which the forecast applies.
`lat`	Latitude of the coordinate.
`lon`	Longitude of the coordinate.
`name`	Name provided in the request for the coord set.
`uwind`, `vwind`, `wind_direction`, `wind_magnitude`	One column per variable or derived expression. Variables default to `[name]\|[level]\|[info]`.

Usage Notes

All times should be in ISO 8601 format (e.g., "2022-08-10T00:00:00Z").
The minHorizon and maxHorizon define the range of forecast hours relative to the fromTime.
You must specify at least one coordinate and one variable.
The asOf parameter allows you to query the data as if you were at a specific point in the past. This means the API will exclude any forecasts generated after the asOf time. This feature is particularly useful for backtesting models and simulations. By setting an asOf time, you can analyze historical forecasts without future data influencing the results, providing a realistic assessment of model performance at that past time. If not provided, the latest available forecast data will be used.

Authentication

You need to include a valid authentication token in the Authorization header. You can obtain a demo token by making a request to:

GET https://gribstream.com/auth/demo

Include the token in your request headers as follows:

Authorization: Bearer <token>

Example cURL Command

curl -X POST 'https://gribstream.com/api/v2/hrrr/history' \
        -H "Content-Type: application/json" \
        -H "Accept-Encoding: gzip" \
        -H "Authorization: Bearer $(curl https://gribstream.com/auth/demo)" \
        -d '{
            "fromTime": "2024-09-10T00:00:00Z",
            "untilTime": "2024-09-10T10:00:00Z",
            "asOf": "2024-09-10T05:00:00Z",
            "minHorizon": 1,
            "maxHorizon": 48,
            "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
            "variables": [
              { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
              { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
            ],
            "expressions": [
              { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
              { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
            ]
        }' | gunzip | head -20

This command retrieves the forecast data and outputs the first 20 lines of the decompressed response.

Error Handling

If there is an error with your request, the API will return an error message with an appropriate HTTP status code.

Common Error Codes

Status Code	Meaning	Description
400 Bad Request	Invalid request parameters.	Occurs when required parameters are missing or have invalid values.
401 Unauthorized	Authentication failed.	Occurs when the authentication token is missing or invalid.
500 Internal Server Error	Server error.	Occurs when there is an error processing the request on the server.

Weather Forecasts Endpoint

Retrieve all forecast runs during a time range, for a list of coordinates, for a list of weather parameters. Optionally filtering for a range of hours ahead (min/max horizons).

POST https://gribstream.com/api/v2/<model>/forecasts