📚 Documentação da API

Guia completo para integração com a Tábua de Marés API

Visão Geral

A Tábua de Marés API fornece dados precisos sobre as marés do litoral brasileiro. Uma API REST completa para desenvolvedores, pesquisadores e entusiastas do mar.

🌐 Base URL: https://tabuamare.devtu.qzz.io//api/v1

📊 Formato: JSON

🚀 Status: Ativo e gratuito

✨ Características

🌊 Cobertura completa: Dados de marés para todo o litoral brasileiro
📍 17 estados costeiros: Informações detalhadas por localização
⚡ Respostas rápidas: API otimizada para performance
🔒 Confiável: Dados oficiais e atualizados

Autenticação

🎉 Uso Livre: Esta API não requer autenticação e é de uso público.

⚡ Limite: 500 requisições por minuto por IP para garantir qualidade do serviço.

Estrutura de Resposta

Todas as respostas seguem o mesmo padrão JSON:

{{code_estrutura_default}}

💡 Observações:

O campo error só aparece quando há erro na requisição

Endpoints

Listar Estados

GET

Retorna a lista de todos os estados costeiros do Brasil disponíveis na API.

GET /states

📝 Exemplo de Requisição:

curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/states" -H "Accept: application/json"

✅ Resposta de Sucesso (200):

{{code_resposta_states}}

🗺️ Estados Disponíveis:

🏖️ AL - Alagoas

🌊 AP - Amapá

🏝️ BA - Bahia

⛵ CE - Ceará

🌅 ES - Espírito Santo

🦀 MA - Maranhão

🐟 PA - Pará

🏖️ PB - Paraíba

🌊 PE - Pernambuco

🏝️ PI - Piauí

⛵ PR - Paraná

🌅 RJ - Rio de Janeiro

🦀 RN - Rio Grande do Norte

🐟 RS - Rio Grande do Sul

🏖️ SC - Santa Catarina

🌊 SE - Sergipe

🏝️ SP - São Paulo

Listar Portos por Estado

GET

Retorna uma lista com os nomes dos portos de um estado específico.

GET /harbor_names/{state}

📋 Parâmetros:

state (string): Sigla do estado em minúsculo (ex: sp, rj, sc, pb)

📝 Exemplo de Requisição:

# Listar portos da Paraíba
curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/harbor_names/pb"

✅ Exemplo de Resposta:

{{code_resposta_harbor_names}}

Obter Portos por IDs

GET

Retorna informações detalhadas de um/mais portos específico pelo seu ID.

GET /harbors/{ids}

📋 Parâmetros:

ids (integer): IDs únicos dos portos separados por vírgula (ex: [1,2,3])

📝 Exemplo de Requisição:

# Obter informações do porto ID 1
curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/harbor/1"

✅ Exemplo de Resposta:

{{code_resposta_harbor_by_id}}

Obter Tábua de Maré por Período

GET

Retorna os dados da tábua de maré para um porto específico em um mês e dias determinados.

GET /tabua-mare/{harbor}/{month}/{days}

📋 Parâmetros:

harbor (integer): ID único do porto
month (integer): Mês desejado (1-12)
days (string): Array de dias no formato "[1,2,10-30]", dias específicos separados por vírgula (ex: 1,30,27) e/ou um período (ex: 1,5-13).

📝 Exemplo de Requisição:

# Obter tábua de maré do porto ID 1 para janeiro, dias 1, 2 e 3
curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/tabua-mare/1/1/[1,2,3]"

# Obter tábua de maré para múltiplos dias
curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/tabua-mare/5/3/[15,16,17,18]"

✅ Exemplo de Resposta:

{{code_resposta_tabua_mare}}

Porto mais próximo (estado)

GET

Retorna o porto mais próximo das coordenadas informadas dentro do estado especificado.

GET /nearested-harbor/{state}/{lat_lng}

📋 Parâmetros:

state (string): Sigla do estado (ex: pb, rj, sp).
lat_lng (string): Coordenadas no formato [lat,lng].

📝 Exemplo de Requisição:

curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/nearested-harbor/pb/[-7.11509,-34.864]"

🧪 Exemplo com Fetch:

fetch(`https://tabuamare.devtu.qzz.io//api/v1/nearested-harbor/pb/[-7.11509,-34.864]`).then(r => r.json())

Porto mais próximo (independente)

GET

Retorna o porto mais próximo das coordenadas informadas sem restringir por estado.

GET /nearest-harbor-independent-state/{lat_lng}

📋 Parâmetros:

lat_lng (string): Coordenadas no formato [lat,lng].

📝 Exemplo de Requisição:

curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/nearest-harbor-independent-state/[-7.11509,-34.864]"

🧪 Exemplo com Fetch:

fetch(`https://tabuamare.devtu.qzz.io//api/v1/nearest-harbor-independent-state/[-7.11509,-34.864]`).then(r => r.json())

Tábua de Maré por Geolocalização

GET

Obtém a tábua de maré do porto mais próximo dentro de um estado, informando apenas coordenadas e período.

GET /geo-tabua-mare/{lat_lng}/{state}/{month}/{days}

📋 Parâmetros:

lat_lng (string): Coordenadas [lat,lng].
state (string): Sigla do estado (ex: pb, rj, sp).
month (integer): Mês (1-12).
days (string): Dias e/ou intervalos (ex: [1,2,10-30]).

📝 Exemplo de Requisição:

curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/geo-tabua-mare/[-7.11509,-34.864]/pb/1/[1,2,3]"

🧪 Exemplo com Fetch:

fetch(`https://tabuamare.devtu.qzz.io//api/v1/geo-tabua-mare/[-7.11509,-34.864]/pb/1/[1,2,3]`).then(r => r.json())

⚙️ Detalhes técnicos

lat_lng é parseado no servidor por um tipo dedicado e suporta negativos e decimais.
days aceita dias e intervalos; o servidor expande e deduplica valores.
O porto é escolhido pela menor distância às coordenadas, respeitando o estado.

🌐 Exemplo: obter sigla do estado com Nominatim

-----AQUI---------

Códigos de Erro

🚨 Códigos HTTP

400 - Bad Request: Requisição malformada ou parâmetros inválidos
404 - Not Found: Recurso não encontrado
500 - Internal Server Error: Erro interno do servidor

📄 Formato de Erro:

{{code_formato_erro}}

1. Primeira requisição:

curl -X GET "https://tabuamare.devtu.qzz.io//api/v1/states"

2. Exemplo JavaScript:

fetch('https://tabuamare.devtu.qzz.io//api/v1/states')
  .then(response => response.json())
  .then(data => console.log(data));

📚 Documentação da API

Visão Geral

✨ Características

Autenticação

Estrutura de Resposta

Endpoints

Listar Estados

📝 Exemplo de Requisição:

✅ Resposta de Sucesso (200):

🗺️ Estados Disponíveis:

Listar Portos por Estado

📋 Parâmetros:

📝 Exemplo de Requisição:

✅ Exemplo de Resposta:

Obter Portos por IDs

📋 Parâmetros:

📝 Exemplo de Requisição:

✅ Exemplo de Resposta:

Obter Tábua de Maré por Período

📋 Parâmetros:

📝 Exemplo de Requisição:

✅ Exemplo de Resposta:

Porto mais próximo (estado)

📋 Parâmetros:

📝 Exemplo de Requisição:

🧪 Exemplo com Fetch:

Porto mais próximo (independente)

📋 Parâmetros:

📝 Exemplo de Requisição:

🧪 Exemplo com Fetch:

Tábua de Maré por Geolocalização

📋 Parâmetros:

📝 Exemplo de Requisição:

🧪 Exemplo com Fetch:

⚙️ Detalhes técnicos

🌐 Exemplo: obter sigla do estado com Nominatim

Códigos de Erro

🚨 Códigos HTTP

📄 Formato de Erro:

Entre em Contato