Riferimento API del catalogo

Elenco dei dataset

GET /api/v2/catalog/datasets

Elenca dataset; filtra per code, family, tag o is_ensemble.

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

Risposta di esempio (campi e voci selezionati):

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

Dettagli di un dataset

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

Consulta un dataset: copertura, frequenza, membri ensemble e fonti.

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

Risposta di esempio (campi e voci selezionati):

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

Il dettaglio di un dataset include native_grid quando è disponibile una griglia nativa verificata. L’oggetto grid usa la specifica dell’inventario: geometria, dimensioni pertinenti, convenzione delle longitudini, proiezione e identificatore della mesh o precisione. Il riepilogo è gratuito e non contiene coppie di coordinate.

total è la dimensione completa della griglia, non il numero nel riquadro. I raster satellitari possono includere posizioni oltre la Terra. Dimensioni e passi sono zero se non pertinenti, come le dimensioni di una mesh non strutturata; interpretali secondo il tipo di griglia.

Per ottenere coppie latitudine/longitudine, usa coordinates_url con un token registrato e i quattro limiti del riquadro. L’inventario consuma crediti; il riepilogo del catalogo no.

Elenco dei parametri

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

Elenca gruppi di parametri, con nomi, unità e numero di varianti.

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

Risposta di esempio (campi e voci selezionati):

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

Dettagli di un parametro

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

Ottieni varianti, livelli, unità e selettori di un parametro. Il nome nel percorso distingue maiuscole e minuscole.

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

Risposta di esempio (campi e voci selezionati):

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

Selettori esatti

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

Ottieni tutti i selettori esatti (name, level, info) in un array piatto per interfacce e scoperta dello schema.

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

Risposta di esempio (campi e voci selezionati):

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

Elenco dei parametri condivisi

GET /api/v2/catalog/shared-parameters

Elenca concetti meteo condivisi; filtra per dataset. Usa dataset_mode=all o any con più dataset.

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

Risposta di esempio (campi e voci selezionati):

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

Dettagli di un parametro condiviso

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

Risolvi un concetto per un dataset. Copia resolved_request nella richiesta; può includere variabili ed espressioni. Controlla prima resolved_supported.

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

Risposta di esempio (campi e voci selezionati):

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