Référence de l’API du catalogue

Liste des jeux de données

GET /api/v2/catalog/datasets

Liste des jeux de données ; filtres code, family, tag ou is_ensemble.

curl 'https://gribstream.com/api/v2/catalog/datasets?code=gfs'

Exemple de réponse (champs et entrées sélectionnés) :

[
  {
    "code": "gfs",
    "name": "GFS",
    "full_name": "Global Forecast System",
    "display_label": "GFS (gfs) - Global Forecast System",
    "provider": "NOAA",
    "is_ensemble": false,
    "parameter_count": 90,
    "models_page_url": "/models/gfs",
    "api_timeseries_url": "/api/v2/gfs/timeseries",
    "api_runs_url": "/api/v2/gfs/runs"
  }
]

Détail d’un jeu de données

GET /api/v2/catalog/datasets/{dataset}

Consultez un jeu de données : couverture, cadence, membres d’ensemble et sources.

curl 'https://gribstream.com/api/v2/catalog/datasets/gfs'

Exemple de réponse (champs et entrées sélectionnés) :

{
  "code": "gfs",
  "name": "GFS",
  "provider": "NOAA",
  "spatial_resolution": {
    "label": "0.25° (~28 km)",
    "kind": "latlon"
  },
  "run_cadence": {
    "label": "00/06/12/18 UTC"
  },
  "min_lead_time": "0h",
  "max_lead_time": "384h",
  "is_ensemble": false,
  "archive_start": "2021-03-22",
  "native_grid": {
    "total": 1038240,
    "grid": {
      "type": "regular_latlon",
      "nx": 1440,
      "ny": 721,
      "firstLat": 90,
      "firstLon": 0,
      "latStep": -0.25,
      "lonStep": 0.25,
      "longitudeConvention": "zero_to_360"
    },
    "coordinates_url": "/api/v2/gfs/native-coordinates"
  },
  "source_url": "https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast"
}

Le détail d’un jeu de données inclut native_grid lorsqu’une grille native vérifiée est disponible. L’objet grid reprend la spécification de l’inventaire : géométrie, dimensions pertinentes, convention de longitude, projection et identifiant de maillage ou précision. Ce résumé est gratuit et ne contient aucune paire de coordonnées.

total est la taille complète de la grille, pas le nombre dans une zone. Les grilles satellite peuvent inclure des positions hors Terre. Dimensions et pas sont nuls lorsqu’ils ne s’appliquent pas, comme les dimensions d’un maillage non structuré ; interprétez-les selon le type de grille.

Pour obtenir les paires latitude/longitude, utilisez coordinates_url avec un token enregistré et les quatre bornes. Cette requête d’inventaire consomme des crédits, contrairement au résumé du catalogue.

Liste des paramètres

GET /api/v2/catalog/datasets/{dataset}/parameters

Liste des groupes de paramètres avec noms, unités et nombre de variantes.

curl 'https://gribstream.com/api/v2/catalog/datasets/gfs/parameters'

Exemple de réponse (champs et entrées sélectionnés) :

[
  {
    "short_name": "TMP",
    "full_name": "Temperature",
    "display_label": "TMP - Temperature",
    "units": "K",
    "variation_count": 57,
    "has_code_table": false,
    "authoritative_sources": [
      {
        "label": "NOAA GRIB2 Table 4.2-0-0",
        "url": "https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table4-2-0-0.shtml"
      }
    ]
  }
]

Détail d’un paramètre

GET /api/v2/catalog/datasets/{dataset}/parameters/{parameter}

Obtenez variantes, niveaux, unités et sélecteurs d’un paramètre. Son nom dans le chemin est sensible à la casse.

curl 'https://gribstream.com/api/v2/catalog/datasets/gfs/parameters/TMP'

Exemple de réponse (champs et entrées sélectionnés) :

{
  "short_name": "TMP",
  "full_name": "Temperature",
  "units": "K",
  "description": "Air temperature is the thermal state of the atmosphere at the specified level. It influences density, stability, and energy exchange.",
  "variations": [
    {
      "level": "2 m above ground",
      "selector": {
        "name": "TMP",
        "level": "2 m above ground",
        "info": ""
      },
      "selector_literal": "{\"name\":\"TMP\",\"level\":\"2 m above ground\",\"info\":\"\"}",
      "introduced_at": "2021-03-22",
      "min_lead_time": "0h",
      "max_lead_time": "384h"
    }
  ]
}

Sélecteurs exacts

GET /api/v2/catalog/datasets/{dataset}/selectors

Obtenez tous les sélecteurs exacts (name, level, info) dans un tableau plat pour les interfaces et la découverte du schéma.

curl 'https://gribstream.com/api/v2/catalog/datasets/gfs/selectors'

Exemple de réponse (champs et entrées sélectionnés) :

[
  {
    "short_name": "TMP",
    "name": "TMP",
    "level": "2 m above ground",
    "info": "",
    "selector": {
      "name": "TMP",
      "level": "2 m above ground",
      "info": ""
    },
    "selector_literal": "{\"name\":\"TMP\",\"level\":\"2 m above ground\",\"info\":\"\"}"
  }
]

Liste des paramètres communs

GET /api/v2/catalog/shared-parameters

Liste des concepts météo communs ; filtre dataset. Utilisez dataset_mode=all ou any pour plusieurs jeux de données.

curl 'https://gribstream.com/api/v2/catalog/shared-parameters'

Exemple de réponse (champs et entrées sélectionnés) :

[
  {
    "code": "wind_speed_10m",
    "label": "Wind speed at 10m",
    "units": "m/s",
    "summary": "Near-surface wind speed normalized to a single output series.",
    "supported_datasets": [
      "gfs",
      "ifsoper"
    ]
  }
]

Détail d’un paramètre commun

GET /api/v2/catalog/shared-parameters/{parameter}

Résolvez un concept pour un jeu de données. Copiez resolved_request dans votre requête ; il peut inclure variables et expressions. Vérifiez d’abord resolved_supported.

curl 'https://gribstream.com/api/v2/catalog/shared-parameters/wind_speed_10m?dataset=ifsoper&alias=wind'

Exemple de réponse (champs et entrées sélectionnés) :

{
  "code": "wind_speed_10m",
  "label": "Wind speed at 10m",
  "units": "m/s",
  "resolved_dataset": "ifsoper",
  "resolved_supported": true,
  "resolved_request": {
    "variables": [
      {
        "name": "10u",
        "level": "sfc",
        "info": "",
        "alias": "u_component",
        "hidden": true
      },
      {
        "name": "10v",
        "level": "sfc",
        "info": "",
        "alias": "v_component",
        "hidden": true
      }
    ],
    "expressions": [
      {
        "expression": "func.Hypot(u_component, v_component)",
        "alias": "wind"
      }
    ]
  }
}