Documentation de l’API de prévisions météorologiques

Cette API donne accès aux données de prévision météorologique pour tous les modèles. Vous pouvez récupérer des données historiques et prévisionnelles en indiquant la plage temporelle, les coordonnées et les variables d’intérêt.

Vous pouvez utiliser notre client Python sur GitHub ou construire votre propre intégration avec les détails ci-dessous.

Si vous intégrez GribStream à un outil d'IA, commencez par GribStream pour les outils d'IA.

Endpoint timeseries

Pour une coordonnée, un paramètre météorologique et une plage temporelle donnés, plusieurs valeurs prévisionnelles sont disponibles. Chaque valeur correspond à un horizon de prévision différent, ou Lead Time, c’est-à-dire une prévision émise à un moment différent dans le passé.

Pour chaque point temporel, l’API renvoie la valeur prévisionnelle avec l’horizon de prévision le plus court. Vous obtenez donc la prévision la plus récente et généralement la plus précise disponible à ce moment. En data science, on parle souvent de série de meilleure prévision (best forecast) ou de nowcast.

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

Renommé Auparavant /history. L’ancien chemin fonctionne toujours.

Modèles disponibles

rap - Rapid Refresh (RAP)
gfs - Global Forecast System (GFS)
gdas - Global Data Assimilation System (GDAS)
nbm - National Blend of Models (NBM) (CONUS core)
nbmak - National Blend of Models (NBM) (Alaska core)
nbmhi - National Blend of Models (NBM) (Hawaii core)
nbmpr - National Blend of Models (NBM) (Puerto Rico core)
nbmgu - National Blend of Models (NBM) (Guam core)
nbmoc - National Blend of Models (NBM) (Oceanic core)
nbmqmd - National Blend of Models QMD (CONUS)
nbmpar - National Blend of Models Parallel (CONUS core, NBM v5)
nbmparak - National Blend of Models Parallel (Alaska core, NBM v5)
nbmparhi - National Blend of Models Parallel (Hawaii core, NBM v5)
nbmparpr - National Blend of Models Parallel (Puerto Rico core, NBM v5)
nbmpargu - National Blend of Models Parallel (Guam core, NBM v5)
nbmparoc - National Blend of Models Parallel (Oceanic core, NBM v5)
nbmparqmd - National Blend of Models Parallel QMD (CONUS, NBM v5)
aigfssfc - AI Global Forecast System Surface (AIGFS Surface)
aigfspres - AI Global Forecast System Pressure Levels (AIGFS Pressure)
aigefssfc - AI Global Ensemble Forecast System Surface (AIGEFS Surface)
aigefspres - AI Global Ensemble Forecast System Pressure Levels (AIGEFS Pressure)
dafsgtg - Domestic Aviation Forecast System Graphical Turbulence Guidance (CONUS)
dafsificonus - Domestic Aviation Forecast System In-Flight Icing (CONUS)
dafsifiak - Domestic Aviation Forecast System In-Flight Icing (Alaska)
cwawrf15 - Taiwan CWA WRF 15 km Regional Forecast
ccpa1hndgd25 - Climatologically Calibrated Precipitation Analysis (1-hour CONUS)
spctstm1hr - SPC HREF Thunderstorm Probability (1 hour)
spctstm4hr - SPC HREF Thunderstorm Probability (4 hour)
spcltg4hr - SPC HREF Lightning-density Probability (4 hour)
spchail4hr - SPC HREF Calibrated Hail Probability (4 hour)
spctor4hr - SPC HREF Calibrated Tornado Probability (4 hour)
spcwind4hr - SPC HREF Calibrated Severe Wind Probability (4 hour)
uvi - NOAA Ultraviolet Index Forecast
fourcastnetgfs - FourCastNet Global Forecast System (FourCastNetGFS)
urma - Unrestricted Mesoscale Analysis (URMA)
rtma - Real-Time Mesoscale Analysis API (RTMA)
hrrr - High-Resolution Rapid Refresh (HRRR)
rrfsprslev - Rapid Refresh Forecast System pressure levels (RRFS)
rrfs2dfld - Rapid Refresh Forecast System 2D fields (RRFS)
refsprslev - Rapid Refresh Forecast System Ensemble (RRFS Ens)
graphcast - GraphCast Global Forecast System (GFS GraphCast)
gefsatmosmean - Global Ensemble Forecast System (GEFS Atmos Mean)
gefsatmos - Global Ensemble Forecast System (GEFS Atmos)
gefschem - Global Ensemble Forecast System (GEFS Chem)
gefswaveprob - Global Ensemble Forecast System (GEFS Wave Prob)
cfsflxf - Climate Forecast System (CFS Radiative Fluxes)
cfspgbf - Climate Forecast System (CFS Pressure)
cfsipvf - Climate Forecast System (CFS Isentropic)
cfsocnf - Climate Forecast System (CFS Ocean)
cdas - Climate Data Assimilation System (CDAS1)
ifsoper - Integrated Forecasting System - Operational (IFS Oper)
ifswave - Integrated Forecasting System - Wave (IFS Wave)
ifsenfo - Integrated Forecasting System - Ensemble Forecast (IFS Enfo)
ifswaef - Integrated Forecasting System - Wave Ensemble Forecast (IFS Waef)
aifsoper - Artificial Intelligence Forecasting System (AIFS)
aifsenfo - Artificial Intelligence Forecasting System Ensemble (AIFS Ensemble)

Headers HTTP de la requête

Header	Valeur	Commentaire
`Content-Type`	`application/json`	Valeur par défaut et seule valeur valide.
`Accept`	Choisissez-en un : `text/csv` `application/json` `application/ndjson`	Sélectionne le format de réponse. Par défaut : `text/csv`
`Accept-Encoding`	`gzip`	Optionnel et recommandé pour une réponse compressée
`Authorization`	`Bearer <token>`	Remplacez <token> par votre token d’authentification

Paramètres du body de requête

Le body de requête doit être un objet JSON avec la structure suivante :

Paramètre	Type	Description	Obligatoire
`fromTime`	`string` (ISO 8601)	Début de la période de prévision.	Oui, soit (fromTime, untilTime), soit timesList
`untilTime`	`string` (ISO 8601)	Fin de la période de prévision.	Oui, soit (fromTime, untilTime), soit timesList
`timesList`	`array` de string (ISO 8601)	Liste explicite d’heures de validité à retourner ; chaque valeur correspond à `forecasted_time`.	Oui, soit (fromTime, untilTime), soit timesList
`asOf`	`string` (ISO 8601)	Heure de coupure/référence : seules les exécutions du modèle générées à cet horodatage ou avant sont prises en compte.	Non
`minLeadTime`	`string` (duration)	Lead Time minimal (inclus). Chaîne de durée comme `"45m"` ou `"18h"`. Prioritaire sur `minHorizon`/`maxHorizon`.	Non
`maxLeadTime`	`string` (duration)	Lead Time maximal (inclus). Chaîne de durée comme `"45m"` ou `"18h"`. Prioritaire sur `minHorizon`/`maxHorizon`.	Non
`minHorizon`	`integer`	Obsolète (utilisez `minLeadTime`). Lead Time minimal en heures (inclus).	Non
`maxHorizon`	`integer`	Obsolète (utilisez `maxLeadTime`). Lead Time maximal en heures (inclus).	Non
`coordinates`	`array` de `coordinate`	Liste de coordonnées géographiques. Optionnel quand `grid` est fourni ; vous pouvez envoyer les deux.	Oui - au moins `coordinates` ou `grid` doit être fourni
`grid`	objet `grid`	Domaine rectangulaire régulier. Le serveur retourne chaque point dans les limites avec le `step` spatial indiqué. Peut être utilisé avec `coordinates`.	Oui - au moins `coordinates` ou `grid` doit être fourni
`variables`	`array` de `variable`	Liste des paramètres météorologiques à récupérer.	Oui
`expressions`	`array` de `expression`	Colonnes calculées côté serveur à partir des variables demandées. Chaque entrée est retournée dans sa propre colonne avec l’alias fourni. Voir la documentation	Non
`filter`	objet `filter`	Filtre booléen appliqué après l’évaluation de toutes les `expressions`. Doit contenir un seul champ `expression` de type `string`. Les lignes pour lesquelles l’expression vaut `false` sont omises de la réponse.	Non
`members`	`array` d’integer	Pour les modèles d’ensemble (`gefsatmos`, `ifsenfo`, `ifswaef` …), ce champ sélectionne les membres d’ensemble à inclure dans la réponse. Exemple : `"members": [2,3,4]`. Par défaut, `[0]` est utilisé et seul le membre 0, la prévision de contrôle, est retourné.	Non (modèles d’ensemble uniquement)

NOTE : l’heure sélectionnée doit être indiquée par la plage (fromTime, untilTime) ou timesList

Objet coordonnée

Champ	Type	Description	Obligatoire
`lat`	`float`	Latitude de la coordonnée.	Oui
`lon`	`float`	Longitude de la coordonnée.	Oui
`name`	`string`	Nom optionnel de la coordonnée, retourné dans la réponse pour identifier l’emplacement.	Non

Objet grille

Champ	Type	Description	Obligatoire
`minLatitude`	number	Bord sud (°N)	Oui
`maxLatitude`	number	Bord nord (°N)	Oui
`minLongitude`	number	Bord ouest (°E)	Oui
`maxLongitude`	number	Bord est (°E)	Oui
`step`	number	Résolution en degrés décimaux	Oui

Objet variable

Les champs name, level et info forment le sélecteur exact de la variable météorologique. Copiez ces valeurs depuis le catalogue ou la page du modèle ; ce sont des identifiants d’API, pas des libellés à traduire.

Consultez la liste complète des paramètres disponibles par modèle.

Champ	Type	Description	Obligatoire
`name`	`string`	Code exact du paramètre météorologique dans le catalogue (par ex. `"TMP"` pour la température). Ne le traduisez pas.	Oui
`level`	`string`	Niveau atmosphérique ou de surface exact du catalogue (par ex. `"2 m above ground"`).	Oui
`info`	`string`	Différenciateur exact lorsque le modèle a plusieurs paramètres avec les mêmes `name` et `level`. Laissez-le vide uniquement si la valeur du catalogue est vide.	Non
`alias`	`string`	Alias optionnel de la variable. S’il est fourni, cet alias est utilisé comme header de colonne dans la réponse.	Non

Objet expression

Champ	Type	Description	Obligatoire
`expression`	`string`	Crée des colonnes calculées. Toutes les variables sélectionnées sont accessibles par leur alias. Voir la documentation	Oui
`alias`	`string`	Nom de colonne utilisé dans la réponse pour ce résultat calculé.	Oui

Objet filtre

Champ	Type	Description	Obligatoire
`expression`	string	Expression booléenne dans le même DSL que `expressions`. Elle peut référencer des alias définis plus haut dans le body de requête.	Oui

Requête d’exemple

POST https://gribstream.com/api/v2/hrrr/timeseries
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",
    "minLeadTime": "1h",
    "maxLeadTime": "48h",
    "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" }
    ]
}

Réponse d’exemple

Le format de réponse est déterminé par le header HTTP Accept. L’API prend en charge trois formats de réponse :

Accept: text/csv - la réponse est un fichier CSV contenant les données de prévision.
Accept: application/json - la réponse est un tableau JSON unique d’objets.
Accept: application/ndjson - la réponse est du JSON délimité par lignes, avec un objet JSON par ligne.

Si le header HTTP Accept-Encoding: gzip est inclus, la réponse sera compressée avec gzip.

NOTE : la réponse n’est pas strictement ordonnée.

Exemple de réponse CSV

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

Exemple de réponse JSON (tableau JSON)

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

Exemple de réponse NDJSON (délimitée par lignes)

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

Champs de la réponse :

Champ	Description
`forecasted_at`	Heure d’exécution du modèle : moment où la prévision a été générée ou émise.
`forecasted_time`	Heure de validité : heure à laquelle la prévision s’applique.
`lat`	Latitude de la coordonnée.
`lon`	Longitude de la coordonnée.
`name`	Nom fourni dans la requête pour le jeu de coordonnées.
`uwind` `vwind` `wind_direction` `wind_magnitude`	Une colonne par variable ou expression dérivée. Par défaut, les variables utilisent `[name]\|[level]\|[info]`.

Notes d’utilisation

Toutes les heures doivent être au format ISO 8601 (par ex. "2022-08-10T00:00:00Z").
Utilisez minLeadTime/maxLeadTime (recommandé) ou les paramètres obsolètes minHorizon/maxHorizon (heures) pour limiter les Lead Times.
Vous devez fournir au moins un emplacement (coordinates et/ou grid) et une variable.
Le paramètre asOf est un horodatage de coupure pour les requêtes rétrospectives. L’API ne prend en compte que les exécutions du modèle générées à asOf ou avant, afin que les backtests et simulations n’utilisent pas par accident des prévisions émises plus tard. S’il n’est pas fourni, les dernières données de prévision disponibles sont utilisées.

Authentification

Vous devez inclure un token d’authentification valide dans le header HTTP Authorization. Pour obtenir un token,

Incluez le token dans les headers HTTP de la requête comme suit :

Authorization: Bearer <token>

Commande cURL d’exemple

curl -X POST 'https://gribstream.com/api/v2/hrrr/timeseries' \
        -H "Content-Type: application/json" \
        -H "Accept-Encoding: gzip" \
        -H "Authorization: Bearer [API_TOKEN]" \
        -d '{
            "fromTime": "2024-09-10T00:00:00Z",
            "untilTime": "2024-09-10T10:00:00Z",
            "asOf": "2024-09-10T05:00:00Z",
            "minLeadTime": "1h",
            "maxLeadTime": "48h",
            "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

Cette commande récupère les données de prévision et affiche les 20 premières lignes de la réponse décompressée.

Gestion des erreurs

En cas d’erreur dans la requête, l’API retourne un message d’erreur avec un code de statut HTTP approprié.

Codes d’erreur courants

Code de statut	Signification	Description
400 Bad Request	Paramètres de requête invalides.	Se produit lorsque des paramètres obligatoires sont manquants ou invalides.
401 Unauthorized	Échec de l’authentification.	Se produit lorsque le token d’authentification est manquant ou invalide.
429 Too Many Requests	Quota dépassé.	Se produit lorsque le quota est épuisé. La réponse inclut un header HTTP `Retry-After` avec le temps d’attente avant de réessayer.
500 Internal Server Error	Erreur serveur.	Se produit lors d’une erreur de traitement côté serveur.

Endpoint runs

Récupère toutes les exécutions de modèle sur une plage temporelle, pour une liste de coordonnées et de paramètres météorologiques. Vous pouvez aussi limiter les résultats à une fenêtre précise de Lead Time.

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

Renommé Auparavant /forecasts. L’ancien chemin fonctionne toujours.