Referencia de la API del catálogo

Lista de datasets

GET /api/v2/catalog/datasets

Lista datasets; filtra por code, family, tag o is_ensemble.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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

Detalle de un dataset

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

Consulta un dataset: cobertura, frecuencia, miembros de ensemble y fuentes.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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

El detalle de un dataset incluye native_grid cuando hay una grilla nativa verificada. Su objeto grid usa la misma especificación que el inventario: tipo de geometría, dimensiones cuando corresponden, convención de longitud, proyección e identificador de malla o precisión. Este resumen es gratuito y no contiene pares de coordenadas.

total es el tamaño completo de la grilla, no la cantidad dentro de una caja. Las grillas satelitales pueden incluir posiciones fuera de la Tierra. Dimensiones y pasos son cero cuando no corresponden, como las dimensiones en una malla no estructurada; interprétalos según el tipo de grilla.

Para obtener pares latitud/longitud, usa coordinates_url con un token registrado y los cuatro límites de la caja. Ese inventario consume créditos; el resumen del catálogo no.

Lista de parámetros

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

Lista grupos de parámetros, con nombres, unidades y cantidad de variantes.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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

Detalle de un parámetro

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

Obtén variantes, niveles, unidades y selectores de un parámetro. Su nombre en la ruta distingue mayúsculas y minúsculas.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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

Selectores exactos

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

Obtén todos los selectores exactos (name, level, info) en un array plano para selectores de interfaz y descubrimiento del esquema.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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

Lista de parámetros compartidos

GET /api/v2/catalog/shared-parameters

Lista conceptos meteorológicos compartidos; filtra por dataset. Usa dataset_mode=all o any para varios datasets.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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

Detalle de un parámetro compartido

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

Resuelve un concepto para un dataset. Copia resolved_request en tu consulta; puede incluir variables y expresiones. Comprueba primero resolved_supported.

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

Ejemplo de respuesta (campos y entradas seleccionados):

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