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. Sign-in to access an OpenAPI spec with Swagger UI.

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 timeList
`untilTime`	`string` (ISO 8601)	End time of the forecast period.	Yes, either (fromTime, untilTime) or timeList
`timeList`	`array` of string (ISO 8601)	Array of forecasted times.	Yes, either (fromTime, untilTime) or timeList
`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

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

Example Request

    POST https://gribstream.com/api/v2/hrrr/history
    Content-Type: application/json
    Accept-Encoding: gzip
    Authorization: Bearer <token>
    Payload:
    {
        "fromTime": "2025-03-10T05:00:00Z",
        "untilTime": "2025-03-10T10:00:00Z",
        "asOf": "2025-03-09T07:30:00Z",
        "minHorizon": 0,
        "maxHorizon": 48,
        "coordinates": [
            { "lat": 29.7604, "lon": -95.3698, "name": "Houston" }
        ],
        "variables": [
            { "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temperature" }
        ],
    }

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,Temperature
    2025-03-09T06:00:00Z,2025-03-10T06:00:00Z,29.760,-95.370,Houston,281.8953
    2025-03-09T06:00:00Z,2025-03-10T08:00:00Z,29.760,-95.370,Houston,280.9348
    2025-03-09T06:00:00Z,2025-03-10T05:00:00Z,29.760,-95.370,Houston,282.6501
    2025-03-09T06:00:00Z,2025-03-10T07:00:00Z,29.760,-95.370,Houston,281.3061
    2025-03-09T06:00:00Z,2025-03-10T09:00:00Z,29.760,-95.370,Houston,280.6853

JSON Response Example (Line-delimited)

    {"temperature":280.9347686767578,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T08:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    {"temperature":282.65013122558594,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T05:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    {"temperature":281.8952941894531,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T06:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    {"temperature":281.30609130859375,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T07:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    {"temperature":280.6852569580078,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T09:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}

NDJSON Response Example (JSON Array)

    [{"temperature":281.30609130859375,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T07:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    ,{"temperature":280.9347686767578,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T08:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    ,{"temperature":281.8952941894531,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T06:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    ,{"temperature":282.65013122558594,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T05:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    ,{"temperature":280.6852569580078,"forecasted_at":"2025-03-09T06:00:00Z","forecasted_time":"2025-03-10T09:00:00Z","lat":29.7604,"lon":-95.3698,"name":"Houston"}
    ]

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.
`temperature`	Alias given to this weather parameter. Defaults to `[name]\|[level]\|[info]`. One of these per selected variable.

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/gfs/history' \
        -H "Content-Type: application/json" \
        -H "Accept-Encoding: gzip" \
        -H "Authorization: Bearer $(curl https://gribstream.com/auth/demo)" \
        -d '{
            "fromTime": "2022-08-10T00:00:00Z",
            "untilTime": "2022-08-13T00:00:00Z",
            "asOf": "2022-08-12T00:00:00Z",
            "minHorizon": 0,
            "maxHorizon": 384,
            "coordinates": [
                { "lat": 40.75, "lon": -73.98 },
                { "lat": 29.75, "lon": -95.36 },
                { "lat": 47.6, "lon": -122.33 }
            ],
            "variables": [
                { "name": "TMP", "level": "2 m above ground", "info": "" },
                { "name": "TMP", "level": "surface", "info": "" }
            ]
        }' | 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