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:
- OGC API - Features, para consulta da rede de boias;
- OGC API - Environmental Data Retrieval (EDR), para consulta das séries temporais de observações.
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¶meter-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¶meter-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¶meter-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¶meter-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¶meter-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 |
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.