Referência da API do catálogo

Lista de datasets

GET /api/v2/catalog/datasets

Lista datasets; filtre por code, family, tag ou is_ensemble.

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

Exemplo de resposta (campos e entradas selecionados):

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

Detalhes de um dataset

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

Consulte um dataset: cobertura, frequência, membros do ensemble e fontes.

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

Exemplo de resposta (campos e entradas selecionados):

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

O detalhe de um dataset inclui native_grid quando há uma grade nativa verificada. O objeto grid usa a mesma especificação do inventário: geometria, dimensões aplicáveis, convenção de longitude, projeção e identificador de malha ou precisão. Este resumo é gratuito e não contém pares de coordenadas.

total é o tamanho completo da grade, não a quantidade em uma caixa. Grades de satélite podem incluir posições fora da Terra. Dimensões e passos são zero quando não se aplicam, como dimensões em uma malha não estruturada; interprete conforme o tipo de grade.

Para obter pares latitude/longitude, use coordinates_url com token registrado e os quatro limites da caixa. Essa consulta consome créditos; o resumo do catálogo não.

Lista de parâmetros

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

Lista grupos de parâmetros, com nomes, unidades e quantidade de variantes.

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

Exemplo de resposta (campos e entradas selecionados):

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

Detalhes de um parâmetro

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

Obtenha variantes, níveis, unidades e seletores de um parâmetro. O nome no caminho diferencia maiúsculas de minúsculas.

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

Exemplo de resposta (campos e entradas selecionados):

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

Seletores exatos

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

Obtenha todos os seletores exatos (name, level, info) em um array plano para interfaces e descoberta do esquema.

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

Exemplo de resposta (campos e entradas selecionados):

[
  {
    "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 compartilhados

GET /api/v2/catalog/shared-parameters

Lista conceitos meteorológicos compartilhados; filtre por dataset. Use dataset_mode=all ou any para vários datasets.

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

Exemplo de resposta (campos e entradas selecionados):

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

Detalhes de um parâmetro compartilhado

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

Resolva um conceito para um dataset. Copie resolved_request na consulta; pode incluir variáveis e expressões. Confira resolved_supported primeiro.

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

Exemplo de resposta (campos e entradas selecionados):

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