API do Sargacast para desenvolvedores

JSON gratuito e somente leitura com o nível diário de sargaço de cada praia da Flórida que acompanhamos, mais uma previsão de 7 dias para cada uma. Sem chave e sem cadastro.

O que é a API

Gratuita: sem chave, sem conta e sem cadastro.
JSON somente leitura por HTTPS: três rotas GET e nada para gravar.
CORS aberto (Access-Control-Allow-Origin: *): uma página web pode chamá-la direto do navegador.
A CDN guarda as respostas por cerca de 5 minutos. Os dados são recalculados a cada hora, quando nosso motor roda.

Primeiros passos

Copie qualquer um destes comandos num terminal; todos funcionam como estão.

Todas as praias com a leitura de hoje

curl https://sargacast.com/api/v1/beaches

A previsão de amanhã para uma zona

curl "https://sargacast.com/api/v1/beaches?zone=miami-beach&day=tomorrow"

Uma praia com a previsão de 7 dias

curl https://sargacast.com/api/v1/beaches/south-pointe

Se os dados estão sendo servidos e quão recentes são

curl https://sargacast.com/api/v1/health

Qualquer página do site em Markdown, para agentes e scripts

curl -H "Accept: text/markdown" https://sargacast.com/en/beaches/south-pointe

Respostas e erros

Toda resposta é um envelope JSON. Um sucesso traz "ok": true e os dados. Um erro traz "ok": false, um status HTTP e um objeto error com um código, uma mensagem e quase sempre uma dica (hint) do que fazer.

Por exemplo, uma praia que não existe:

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "No beach with slug no-such-beach",
    "hint": "List the beach slugs with GET https://sargacast.com/api/v1/beaches (the slug field of each entry). The public API is described at https://sargacast.com/openapi.json and https://sargacast.com/en/developers."
  }
}

Os códigos de erro:

validation_failed (422): um parâmetro é inválido; a dica diz qual e os valores aceitos.
not_found (404): nenhuma praia tem esse slug ou o caminho não faz parte da API; a dica diz como listar os slugs.
method_not_allowed (405): a API é somente leitura; use GET.
unavailable (503) e internal (500): o banco de dados não respondeu ou uma consulta falhou. Tente de novo em alguns minutos.

O que cada campo significa

index_value: o Sargaçômetro, de 0 (nada) a 10 (muito). É null quando uma praia não tem dados recentes.
level: o medidor em palavras: clean (0–3), moderate (4–6) ou heavy (7–10).
status: ok para uma leitura recente, stale quando a última leitura está mais velha do que deveria (aparece mesmo assim, com a idade), no_data quando não há nada recente.
confidence: de 0 a 1, quanto se pode confiar no valor. Sobe com mais fontes e mais recentes.
computed_at: quando nosso motor calculou a leitura pela última vez (a cada hora). Não é a passagem do satélite: o dado de satélite é um composto de 7 dias, e cada página de praia mostra a data dele.
forecast (só uma praia): até 7 dias, cada um com date, index_value, level, confidence, lead_days (dias desde o cálculo, 0 para o mesmo dia) e kind: forecast para lead_days 0 a 3, trend para os dias seguintes, que são uma tendência mais aproximada.
zone_slug é o que ?zone= filtra; reports_today conta os relatos da comunidade de hoje nessa praia.

Documentação para máquinas

Termos de uso

Uso gratuito, inclusive em apps e artigos, com o crédito visível “Data: Sargacast (sargacast.com)” e um link para o site.
Guarde as respostas em cache e evite passar de cerca de uma consulta por minuto por cliente.
É um guia, não um aviso oficial de segurança ou de saúde.
Para uso intenso ou comercial, ou um volume maior, escreva para: hola@sargacast.com

Dúvidas

Dúvidas, um erro ou um campo que você gostaria de ver: uma única pessoa lê cada mensagem em hola@sargacast.com