Documentação

API de Balneabilidade

Acesse programaticamente dados oficiais de balneabilidade das praias do Brasil. Gratuita, sem cadastro, CORS liberado. Sempre cite a fonte ao exibir os dados.

CORS liberado

Consuma diretamente do browser, sem proxy.

Sem autenticação

Acesso gratuito e aberto, sem chave de API.

Dados oficiais

Coletados de órgãos ambientais estaduais.

Baixar OpenAPIVer endpoints
Base URL:https://praiaemdia.com.br
Consultar dados interativamente →

Schema de dados

Schema: objeto Praia

Retornado em /api/v1/praias e /api/v1/praias/{id}

CampoTipoDescrição
idstringIdentificador único (ex.: AL:1).
praiastringNome do ponto de monitoramento.
cidadestringMunicípio.
estadostring (UF)Sigla do estado (ex.: AL, SP).
regiaostringRegião geográfica (Norte, Nordeste…).
latnumberLatitude decimal.
lonnumberLongitude decimal.
categoria"propria" | "impropria"Resultado da última coleta.
coletaEmstring (DD/MM/AAAA)Data da última coleta.
fontestringSigla do órgão ambiental (ex.: IMA-AL).
fonteUrlstring (URL)URL do órgão de origem.
tempCnumber | undefinedTemperatura da água em °C (quando disponível).
chuvanumber | undefinedChuva acumulada em mm (quando disponível).
horastring | undefinedHora da coleta HH:mm (quando disponível).

Endpoints

GET/api/v1/praias

Lista paginada de pontos de monitoramento de balneabilidade. Filtre por estado, cidade, status e texto livre.

Parâmetros

ParâmetroTipoObrigatórioDescrição
estadostringnãoSigla do estado (ex.: AL, SP, RJ).
cidadestringnãoNome da cidade (ex.: Santos, Maceió).
status"propria" | "impropria"nãoFiltra pelo resultado da última coleta.
qstringnãoBusca textual pelo nome da praia.
limitnumbernãoMáximo de resultados por página. Padrão: 50, máximo: 500.
offsetnumbernãoDeslocamento para paginação. Padrão: 0.

Exemplo de requisição

bash
curl -G "https://praiaemdia.com.br/api/v1/praias" \
  --data-urlencode "estado=AL" \
  --data-urlencode "status=propria" \
  --data-urlencode "limit=10"

Exemplo de resposta

json
{
  "total": 42,
  "limit": 10,
  "offset": 0,
  "pontos": [
    {
      "id": "AL:1",
      "praia": "Pajuçara",
      "cidade": "Maceió",
      "estado": "AL",
      "regiao": "Nordeste",
      "lat": -9.6658,
      "lon": -35.7172,
      "categoria": "propria",
      "coletaEm": "10/06/2025",
      "fonte": "IMA-AL",
      "fonteUrl": "https://ima.al.gov.br/balneabilidade",
      "tempC": 28.5,
      "chuva": 0,
      "hora": "08:00"
    }
    // ...
  ]
}
GET/api/v1/praias/{id}

Retorna os dados completos de um único ponto de monitoramento. O id segue o padrão {UF}:{numero} (ex.: AL:1, SP:42).

Parâmetros

ParâmetroTipoObrigatórioDescrição
idstringsimIdentificador único do ponto no formato UF:numero (ex.: AL:1).

Exemplo de requisição

bash
curl "https://praiaemdia.com.br/api/v1/praias/AL:1"

Exemplo de resposta

json
{
  "id": "AL:1",
  "praia": "Pajuçara",
  "cidade": "Maceió",
  "estado": "AL",
  "regiao": "Nordeste",
  "lat": -9.6658,
  "lon": -35.7172,
  "categoria": "propria",
  "coletaEm": "10/06/2025",
  "fonte": "IMA-AL",
  "fonteUrl": "https://ima.al.gov.br/balneabilidade",
  "tempC": 28.5,
  "chuva": 0,
  "hora": "08:00"
}
GET/api/v1/estados

Resumo dos estados cobertos pela plataforma, com contagem total de pontos e breakdown própria/imprópria.

Exemplo de requisição

bash
curl "https://praiaemdia.com.br/api/v1/estados"

Exemplo de resposta

json
{
  "total": 9,
  "estados": [
    {
      "uf": "AL",
      "nome": "Alagoas",
      "total": 47,
      "propria": 39,
      "impropria": 8
    },
    {
      "uf": "BA",
      "nome": "Bahia",
      "total": 120,
      "propria": 95,
      "impropria": 25
    }
    // ...
  ]
}
GET/api/serie

Série histórica de coletas de um ponto específico. Retorna todas as entradas disponíveis com data e categoria.

Parâmetros

ParâmetroTipoObrigatórioDescrição
idstringsimIdentificador do ponto no formato UF:numero (ex.: AL:1).

Exemplo de requisição

bash
curl "https://praiaemdia.com.br/api/serie?id=AL:1"

Exemplo de resposta

json
{
  "id": "AL:1",
  "serie": [
    { "coletaEm": "10/06/2025", "categoria": "propria" },
    { "coletaEm": "03/06/2025", "categoria": "propria" },
    { "coletaEm": "27/05/2025", "categoria": "impropria" },
    { "coletaEm": "20/05/2025", "categoria": "propria" }
  ]
}
GET/api/openapi

Especificação OpenAPI 3.0 completa da API em formato JSON. Importe em Swagger UI, Insomnia, Postman, ou qualquer cliente compatível.

Exemplo de requisição

bash
curl "https://praiaemdia.com.br/api/openapi" | python3 -m json.tool

Exemplo de resposta

json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Praia em Dia API",
    "version": "1.0.0",
    "description": "API de balneabilidade das praias do Brasil"
  },
  "paths": {
    "/api/v1/praias": { ... },
    "/api/v1/praias/{id}": { ... },
    "/api/v1/estados": { ... },
    "/api/serie": { ... }
  }
}

Usar via Inteligência Artificial

Usar via Inteligência Artificial

Há um prompt Markdown pronto em /api/ai-prompt.md que descreve a API ao seu assistente de IA de forma estruturada. Aponte qualquer LLM (ChatGPT, Claude, Gemini, etc.) para essa URL e ele saberá consultar os dados de balneabilidade diretamente.

Como usar

  1. 1Copie a URL do prompt abaixo e cole como contexto ou instrução de sistema do seu assistente.
  2. 2O assistente lerá o prompt e saberá como consultar a API para responder perguntas como “Quais praias de Maceió estão próprias para banho hoje?”
  3. 3Para agentes com acesso à internet: referencie a URL diretamente. Para ambientes sem acesso, copie e cole o conteúdo do arquivo como contexto.
markdown
# Instrução para o assistente
Consulte o prompt da API em: https://praiaemdia.com.br/api/ai-prompt.md
Use a API descrita para responder perguntas sobre balneabilidade das praias do Brasil.
Abrir prompt

Boas práticas

Boas práticas e atribuição

  • CORS liberado — todas as rotas respondem com Access-Control-Allow-Origin: *, então você pode consumir a API direto do browser sem proxy.
  • Cite a fonte — ao exibir os dados, deixe visível um crédito a “Praia em Dia” com link para praiaemdia.com.br.
  • Dados oficiais — as informações vêm diretamente de órgãos ambientais estaduais. Sempre oriente o usuário final a confirmar na fonte original antes de entrar na água. O campo fonteUrl aponta para o órgão de origem.
  • Paginação — use limit e offset para não sobrecarregar a API. O valor máximo de limit é 500.
  • Resolução CONAMA 274/2000 — os critérios de classificação própria/imprópria seguem esta resolução federal. Consulte-a para detalhes técnicos sobre os limites microbiológicos adotados.