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.
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.
Header | Value |
---|---|
Content-Type |
application/json |
Accept-Encoding |
gzip (optional, for compressed response) |
Authorization |
Bearer <token> (replace <token> with your authentication token) |
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 |
Field | Type | Description | Required |
---|---|---|---|
lat |
float |
Latitude of the coordinate. | Yes |
lon |
float |
Longitude of the coordinate. | Yes |
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 |
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": "" } ] }
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. |
"2022-08-10T00:00:00Z"
).minHorizon
and maxHorizon
define the range of forecast hours relative to the fromTime
.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.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>
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.
If there is an error with your request, the API will return an error message with an appropriate HTTP status code.
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. |
If you have any questions or need assistance, please contact our support team at info@gribstream.com.
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.
Header | Value |
---|---|
Content-Type |
application/json |
Accept-Encoding |
gzip (optional, for compressed response) |
Authorization |
Bearer <token> (replace <token> with your authentication token) |
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 |
Field | Type | Description | Required |
---|---|---|---|
lat |
float |
Latitude of the coordinate. | Yes |
lon |
float |
Longitude of the coordinate. | Yes |
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 |
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": "" } ] }
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. |
"2022-08-10T00:00:00Z"
).minHorizon
and maxHorizon
define the range of forecast hours relative to the fromTime
.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>
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.
If there is an error with your request, the API will return an error message with an appropriate HTTP status code.
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. |
If you have any questions or need assistance, please contact our support team at info@gribstream.com.