GribStream

Weather Forecast API Documentation

This API provides access to weather forecast data from the RAP, GFS and NBM 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.

Endpoints

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
    

Replace <model> with either rap, gfs or nbm to select the weather model.

Available Models

Request Headers

Header Value
Content-Type application/json
Accept-Encoding gzip (optional, 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
untilTime string (ISO 8601) End time of the forecast period. Yes
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

Coordinate Object

Field Type Description Required
lat float Latitude of the coordinate. Yes
lon float Longitude of the coordinate. Yes

Variable Object

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 Additional information (can be empty). No

Example Request

    POST https://gribstream.com/api/v2/gfs/history
    Content-Type: application/json
    Accept-Encoding: gzip
    Authorization: Bearer <token>

    {
        "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": "" }
        ]
    }
    

Example Response

The response is a CSV file containing the forecast data for the specified parameters. If the Accept-Encoding: gzip header is included, the response will be gzip-compressed.

NOTE: The response is not strictly in-order.

    forecasted_at,forecasted_time,lat,lon,TMP|2 m above ground|,TMP|surface|
    2022-08-10T06:00:00Z,2022-08-10T06:00:00Z,47.60,-122.33,287.28,286.83
    2022-08-10T06:00:00Z,2022-08-10T06:00:00Z,40.75,-73.98,296.98,296.93
    2022-08-10T06:00:00Z,2022-08-10T06:00:00Z,29.75,-95.36,300.38,299.93
    2022-08-10T12:00:00Z,2022-08-10T12:00:00Z,47.60,-122.33,286.80,286.10
    2022-08-10T12:00:00Z,2022-08-10T12:00:00Z,40.75,-73.98,296.70,297.80
    2022-08-10T12:00:00Z,2022-08-10T12:00:00Z,29.75,-95.36,299.70,299.30
    2022-08-10T12:00:00Z,2022-08-10T15:00:00Z,47.60,-122.33,290.05,290.66
    2022-08-10T12:00:00Z,2022-08-10T15:00:00Z,40.75,-73.98,298.55,300.36
    ...
    

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.
TMP|2 m above ground| Temperature at 2 meters above ground level.
TMP|surface| Temperature at the surface.

Usage Notes

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.

Contact Information

If you have any questions or need assistance, please contact our support team at info@gribstream.com.

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
    

Replace <model> with either rap, gfs or nbm to select the weather model.

Available Models

Request Headers

Header Value
Content-Type application/json
Accept-Encoding gzip (optional, 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
forecastedFrom string (ISO 8601) Earliest forecast run time. Yes
forecastedUntil string (ISO 8601) Latest forecast run time. Yes
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

Coordinate Object

Field Type Description Required
lat float Latitude of the coordinate. Yes
lon float Longitude of the coordinate. Yes

Variable Object

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 Additional information (can be empty). No

Example Request

    POST https://gribstream.com/api/v2/nbm/forecasts
    Content-Type: application/json
    Accept-Encoding: gzip
    Authorization: Bearer <token>

    {
        "forecastedFrom": "2024-09-10T00:00:00Z",
        "forecastedUntil": "2024-09-10T00:00:00Z",
        "minHorizon": 1,
        "maxHorizon": 10,
        "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": "WIND", "level": "10 m above ground", "info": "" },
            { "name": "DPT", "level": "2 m above ground", "info": "" }
        ]
    }
    

Example Response

The response is a CSV file containing the forecast data for the specified parameters. If the Accept-Encoding: gzip header is included, the response will be gzip-compressed.

NOTE: The response is not strictly in-order.

    forecasted_at,forecasted_time,lat,lon,DPT|2 m above ground|,TMP|2 m above ground|,WIND|10 m above ground|
    2024-09-10T00:00:00Z,2024-09-10T09:00:00Z,29.75,-95.36,291.190,297.140,4.000
    2024-09-10T00:00:00Z,2024-09-10T09:00:00Z,40.75,-73.98,288.390,293.140,6.400
    2024-09-10T00:00:00Z,2024-09-10T09:00:00Z,47.60,-122.33,285.190,286.340,0.400
    2024-09-10T00:00:00Z,2024-09-10T10:00:00Z,29.75,-95.36,291.090,296.630,4.000
    2024-09-10T00:00:00Z,2024-09-10T10:00:00Z,40.75,-73.98,288.290,292.630,6.000
    2024-09-10T00:00:00Z,2024-09-10T10:00:00Z,47.60,-122.33,284.690,285.830,0.400
    2024-09-10T00:00:00Z,2024-09-10T08:00:00Z,29.75,-95.36,291.390,297.430,3.600
    2024-09-10T00:00:00Z,2024-09-10T08:00:00Z,40.75,-73.98,288.590,293.430,6.800
    2024-09-10T00:00:00Z,2024-09-10T08:00:00Z,47.60,-122.33,285.390,286.630,0.400
    2024-09-10T00:00:00Z,2024-09-10T06:00:00Z,29.75,-95.36,291.670,297.920,3.600
    2024-09-10T00:00:00Z,2024-09-10T06:00:00Z,40.75,-73.98,288.470,293.920,6.800
    2024-09-10T00:00:00Z,2024-09-10T06:00:00Z,47.60,-122.33,285.670,287.520,0.800
    ...
    

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.
DPT|2 m above ground| Dew Point Temperature at 2 meters above ground level.
TMP|2 m above ground| Temperature at 2 meters above ground level.
WIND|10 m above ground| Wind Speed at 10 m above ground level.

Usage Notes

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/nbm/forecasts' \
        -H "Content-Type: application/json" \
        -H "Accept-Encoding: gzip" \
        -H "Authorization: $(curl https://gribstream.com/auth/demo)" \
        -d '{
        "forecastedFrom": "2024-09-10T00:00:00Z",
        "forecastedUntil": "2024-09-10T00:00:00Z",
        "minHorizon": 1,
        "maxHorizon": 10,
        "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": "WIND", "level": "10 m above ground", "info": "" },
            { "name": "DPT", "level": "2 m above ground", "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.

Contact Information

If you have any questions or need assistance, please contact our support team at info@gribstream.com.