Skip to main content

OGC API EDR - Rede de boias Datawell Waverider - Observações

Versão beta.

1. Introdução

Esta página descreve o acesso aos dados de observação de agitação marítima e temperatura da superfície do mar (sea surface temperature, SST), adquiridos pela rede de boias Datawell Waverider, e disponibilizados em tempo-quase-real (NRT) pelo Instituto Hidrográfico (IH) através de uma OGC API.

A implementação segue as normas do Open Geospatial Consortium (OGC), combinando:

A OGC API encontra-se disponível em:

https://ogcapi.hidrografico.pt

A descrição OpenAPI / Swagger pode ser consultada através da ligação disponibilizada na página inicial da OGC API.


2. Coleção buoys_datawell

2.1. Características gerais

A rede de boias Datawell Waverider e as respetivas observações estão publicadas na coleção buoys_datawell:

https://ogcapi.hidrografico.pt/collections/buoys_datawell

As datas e horas são expressas em Tempo Universal Coordenado (UTC), segundo a norma ISO 8601.

O serviço disponibiliza parâmetros de agitação marítima e temperatura da superfície do mar, acompanhados pelos respetivos indicadores de controlo de qualidade (QC).

As observações apresentam uma resolução temporal de 30 minutos e são disponibilizadas numa janela temporal móvel de 15 dias.

As posições das boias utilizam o sistema de referência horizontal OGC CRS84 (WGS 84, longitude/latitude).

O identificador de cada boia corresponde ao atributo id_est e é comum às consultas OGC API - Features e OGC API - EDR.

O serviço disponibiliza apenas observações em NRT, não integrando previsões de agitação marítima ou de SST.

2.2. Instância de dados

A instância disponível pode ser consultada através de:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances?f=json
Instância Processamento QC Resolução temporal Latência Janela temporal
nrt L2 Com QC automático 30 minutos 30 minutos 15 dias

As consultas que não especifiquem explicitamente uma instance utilizam nrt por omissão.

A instância nrt disponibiliza os tipos de consulta locations, area e radius.

2.3. Consultas disponíveis

Objetivo Interface Consulta Resposta
Consultar a rede de boias OGC API - Features /items GeoJSON
Consultar as instâncias disponíveis OGC API - EDR /instances JSON
Consultar as boias disponíveis OGC API - EDR /instances/nrt/locations GeoJSON
Consultar a série temporal de uma boia OGC API - EDR /instances/nrt/locations/{locationId} CoverageJSON
Consultar por área OGC API - EDR /instances/nrt/area CoverageJSON
Consultar por distância a um ponto OGC API - EDR /instances/nrt/radius CoverageJSON

3. Acesso aos dados

3.1. Metadados da coleção

Os metadados da rede de boias Datawell Waverider podem ser consultados no Catálogo de Metadados do IH. A série temporal de dados de cada uma das boias do IH possui uma ficha de metadados específica, cuja licença de utilização é distinta da rede boias:

A descrição da coleção na OGC API pode ser consultada em HTML ou JSON:

# HTML
https://ogcapi.hidrografico.pt/collections/buoys_datawell?f=html

# JSON
https://ogcapi.hidrografico.pt/collections/buoys_datawell?f=json

A resposta inclui, entre outros elementos:

  • Título, descrição e palavras-chave;
  • Extensão espacial da rede de boias;
  • Ligações para metadados, licença, vocabulários e sistemas de referência;
  • Parâmetros disponíveis;
  • Tipos de consulta suportados.

3.2. Rede de boias

A rede de boias é disponibilizada através de OGC API - Features:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/items?f=json

O endpoint devolve um objeto GeoJSON do tipo FeatureCollection. O número de boias pode ser limitado com o parâmetro limit:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/items?f=json&limit=10

Também é possível filtrar espacialmente as boias através de um retângulo delimitador (bbox), com os limites ordenados por longitude mínima, latitude mínima, longitude máxima e latitude máxima (OGC CRS84):

https://ogcapi.hidrografico.pt/collections/buoys_datawell/items?f=json&bbox=-10,36,-7,42

No contexto OGC API - EDR, as boias disponíveis podem ser consultadas através de:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/locations?f=json&limit=10

Os principais atributos disponibilizados para cada boia são:

Atributo Descrição Formato
id_est Identificador único da boia e locationId utilizado nas consultas OGC API - EDR. Número inteiro
id_fund Identificador único do fundeamento associado à boia. Número inteiro
name Designação da boia. Texto
area Área ou local associado à boia. Texto
wmo_id Identificador WMO da boia. Número inteiro
aton_id Identificador único da ajuda à navegação (lista de luzes). Texto
depth Profundidade no local da boia. Número decimal (metros)
status Estado da boia: active, inactive ou unknown. Texto
nrt Informação sobre a disponibilidade de dados em NRT: near-real-time data available ou near-real-time data not available. Texto
last_pos Data e hora da posição mais recente disponível. UTC (ISO 8601)
last_sea Data e hora da observação oceanográfica mais recente disponível. UTC (ISO 8601)
entity Entidade associada à boia, quando aplicável. Texto (URI)
geometry Geometria da boia. GeoJSON Point - OGC CRS84 (longitude, latitude)

Nas consultas  OGC API - EDR /locations são consideradas apenas as boias para as quais existe uma localização geográfica disponível.

3.3. Parâmetros comuns às consultas OGC API - EDR

As consultas OGC API - EDR utilizam os seguintes argumentos comuns:

Argumento Descrição / formato Exemplo
instanceId Instância de dados indicada no caminho do endpoint. nrt
datetime Instante ou intervalo temporal em UTC (ISO 8601). YYYY-MM-DDThh:mm:ssZ/YYYY-MM-DDThh:mm:ssZ
parameter-name Parâmetro ou lista de parâmetros separados por vírgula. wave_hm0,wave_tp
f Formato da resposta. json

O argumento datetime pode assumir as seguintes formas:

  • Instante: datetime=YYYY-MM-DDThh:mm:ssZ;
  • Intervalo fechado: datetime=início/fim;
  • Intervalo com início aberto: datetime=../fim;
  • Intervalo com fim aberto: datetime=início/...

As janelas temporais utilizadas quando datetime é omitido e os limites operacionais das consultas são apresentados na secção 3.6.

Quando o argumento parameter-name é omitido, são devolvidos todos os parâmetros disponíveis, incluindo os parâmetros físicos e os respetivos indicadores QC.

3.4. Série temporal de uma boia

A série temporal de uma boia é obtida através da consulta:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/locations/{locationId}

O argumento locationId corresponde ao atributo id_est da boia.

Os identificadores disponíveis podem ser obtidos previamente através de:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/locations?f=json

Exemplo de uma consulta para um identificador genérico {locationId}:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/locations/{locationId}?f=json&parameter-name=wave_hm0

É possível solicitar vários parâmetros na mesma consulta:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/locations/{locationId}?f=json&parameter-name=wave_hm0,wave_tp,wave_thtp,sea_water_temperature

Para incluir os indicadores de controlo de qualidade:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/locations/{locationId}?f=json&parameter-name=wave_hm0,wave_hm0_qc,wave_tp,wave_tp_qc

3.5. Consultas espaciais

As consultas espaciais area e radius selecionam boias existentes e não realizam interpolação espacial. Cada boia selecionada é devolvida como uma série temporal independente.

3.5.1. Consulta por área

A consulta area seleciona as boias cuja localização intersecta a área definida por um polígono ou multipolígono:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/area
Argumento Descrição Exemplo
coords Geometria WKT do tipo POLYGON ou MULTIPOLYGON (OGC CRS84). POLYGON((-9.2 36.7,-7.7 36.7,-7.7 41.5,-9.2 41.5,-9.2 36.7))

Exemplo no browser:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/area?coords=POLYGON%28%28-9.2%2036.7%2C-7.7%2036.7%2C-7.7%2041.5%2C-9.2%2041.5%2C-9.2%2036.7%29%29&parameter-name=wave_hm0,wave_tp&f=json

Exemplo no terminal:

curl --get \
  'https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/area' \
  --data-urlencode 'coords=POLYGON((-9.2 36.7,-7.7 36.7,-7.7 41.5,-9.2 41.5,-9.2 36.7))' \
  --data-urlencode 'parameter-name=wave_hm0,wave_tp' \
  --data-urlencode 'f=json'
3.5.2. Consulta por raio

A consulta radius seleciona as boias localizadas dentro de uma determinada distância a um ponto ou conjunto de pontos:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/radius
Argumento Descrição Exemplo
coords Geometria WKT do tipo POINT ou MULTIPOINT (OGC CRS84). POINT(-8.93 37.92)
within Distância máxima. 20
within-units Unidade da distância: m, km ou nmi. km

Exemplo no browser:

https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/radius?coords=POINT%28-8.93%2037.92%29&within=20&within-units=km&parameter-name=wave_hm0&f=json

Exemplo no terminal:

curl --get \
  'https://ogcapi.hidrografico.pt/collections/buoys_datawell/instances/nrt/radius' \
  --data-urlencode 'coords=POINT(-8.93 37.92)' \
  --data-urlencode 'within=20' \
  --data-urlencode 'within-units=km' \
  --data-urlencode 'parameter-name=wave_hm0' \
  --data-urlencode 'f=json'

3.6. Janelas temporais e limites operacionais

Quando o argumento datetime é omitido, o serviço utiliza as janelas temporais indicadas na tabela seguinte.

Consulta Janela temporal por omissão Limite por pedido
/instances/nrt/locations Não aplicável 100 boias
/instances/nrt/locations/{locationId} 24 horas, terminando no momento atual 10 000 observações
/instances/nrt/area 1 hora, terminando no momento atual 20 boias e 10 000 observações
/instances/nrt/radius 1 hora, terminando no momento atual 20 boias e 10 000 observações

Quando fornecido explicitamente, o argumento datetime deve estar compreendido na janela temporal disponível, correspondente aos 15 dias mais recentes.


4. Estrutura e semântica dos dados

4.1. Estrutura da resposta CoverageJSON

As consultas OGC API - EDR de observações devolvem um objeto CoverageJSON do tipo CoverageCollection. Cada boia selecionada é representada por uma Coverage com domínio PointSeries.

Elemento Conteúdo
type Tipo do objeto, normalmente CoverageCollection.
domainType Tipo de domínio, nesta coleção PointSeries.
parameters Metadados semânticos dos parâmetros, incluindo propriedade observada, unidade de medida e informação QC.
coverages[].id Identificador id_est da boia.
coverages[].domain.axes.x Longitude da boia.
coverages[].domain.axes.y Latitude da boia.
coverages[].domain.axes.t Instantes das observações.
coverages[].ranges.{parameter}.values Valores do parâmetro solicitado.
coverages[].ranges.{parameter}_qc.values Códigos QC associados ao parâmetro.

Exemplo simplificado da estrutura da resposta:

{
  "type": "CoverageCollection",
  "domainType": "PointSeries",
  "parameters": {
    "wave_hm0": {},
    "wave_hm0_qc": {},
    "wave_tp": {}
  },
  "coverages": [
    {
      "type": "Coverage",
      "id": "19",
      "domain": {
        "axes": {
          "x": {"values": [-9.0]},
          "y": {"values": [38.0]},
          "t": {
            "values": [
              "2026-10-07T12:00:00Z",
              "2026-10-07T12:30:00Z"
            ]
          }
        }
      },
      "ranges": {
        "wave_hm0": {"values": [1.2, 1.3]},
        "wave_hm0_qc": {"values": [1, 1]},
        "wave_tp": {"values": [8.4, 8.6]}
      }
    }
  ]
}

Os valores e coordenadas apresentados neste exemplo são meramente ilustrativos e destinam-se apenas a demonstrar a estrutura da resposta.

4.2. Parâmetros

Parâmetro Descrição Unidade Formato
wave_hm0 Altura significativa da onda (NVS P09 VHM0) m (NVS P06 ULAA) Número decimal
wave_hm0_qc Código QC associado a wave_hm0 (NVS L20) - Número inteiro
wave_hmax Altura máxima da onda (NVS P07 JNQS0CMX) m (NVS P06 ULAA) Número decimal
wave_hmax_qc Código QC associado a wave_hmax (NVS L20) - Número inteiro
wave_tp Período de pico (NVS P07 CFV13N31) s (NVS P06 UTBB) Número decimal
wave_tp_qc Código QC associado a wave_tp (NVS L20) - Número inteiro
wave_tm02 Período médio espetral (NVS P07 CFV8N75) s (NVS P06 UTBB) Número decimal
wave_tm02_qc Código QC associado a wave_tm02 (NVS L20) - Número inteiro
wave_thtp Direção média no período de pico (NVS P07 P9IY6NIQ) ° (NVS P06 UAAA) Número decimal
wave_thtp_qc Código QC associado a wave_thtp (NVS L20) - Número inteiro
wave_sprtp Dispersão no período de pico (NVS P07 X37RPE7M) ° (NVS P06 UAAA) Número decimal
wave_sprtp_qc Código QC associado a wave_sprtp (NVS L20) - Número inteiro
sea_water_temperature Temperatura da superfície do mar (NVS P07 CFSN0335) °C (NVS P06 UPAA) Número decimal
sea_water_temperature_qc Código QC associado a sea_water_temperature (NVS L20) - Número inteiro

Para solicitar a altura significativa e o período de pico:

parameter-name=wave_hm0,wave_tp

Para solicitar também os respetivos indicadores de QC:

parameter-name=wave_hm0,wave_hm0_qc,wave_tp,wave_tp_qc

4.3. Vocabulários e sistemas de referência

Elemento Referência
Sistema de referência horizontal - OGC CRS84 (WGS 84, longitude/latitude) OGC CRS84
Sistema temporal Calendário Gregoriano; UTC (ISO 8601).
Vocabulários

NVS P06, NVS P07, NVS P09 e NVS L20


5. Termos, condições e acesso

5.1. Licença e condições de utilização

Os dados são disponibilizados nos termos da licença CC BY 4.0 (rede de boias) e CC BY-NC 4.0 (séries temporais), conforme indicado nos respetivos metadados, requerendo, entre outros:

  • Identificar a fonte dos dados;
  • Manter a referência aos metadados, DOI e à licença aplicável;
  • Indicar alterações ou transformações realizadas sobre os dados, quando aplicável;
  • Não atribuir aos dados uma precisão, validação ou nível de qualidade superior ao declarado;
  • Considerar os indicadores de controlo de qualidade associados às observações.

As observações são disponibilizadas em NRT e podem conter falhas, atrasos, valores ausentes ou anomalias instrumentais. O utilizador é responsável pela avaliação da adequação dos dados à finalidade pretendida.

5.2. Autenticação

Na configuração atual, o acesso aos endpoints descritos não requer autenticação nem API key.