Documentação da API
Integre previsões de qualidade do pôr do sol em suas aplicações
Obtenha uma chave de API para rastrear seu usoInício Rápido
Obtenha uma previsão de pôr do sol em segundos
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Substitua $SUNSET_API_KEY por uma chave do seu painel. Chamadas não autenticadas funcionam para demos rápidas, mas são mais restritas e não incluem cabeçalhos de rate limit.
Exemplo de Resposta
{
"score": 78,
"label": "High",
"explanation": "Scattered clouds and clean air should produce vivid colors near the horizon.",
"confidence": "high",
"location": "Paris, FR",
"predictionType": "sunset",
"sunsetTime": "2026-05-26T19:42:00Z",
"sunriseTime": "2026-05-26T04:51:00Z",
"timezone": "Europe/Paris",
"targetDate": "2026-05-26",
"rawFactors": {
"cloudCover": 15,
"humidity": 55,
"visibility": 18200,
"windSpeed": 5.2,
"windDegree": 180,
"rainProb": 0,
"condition": "clouds",
"temperature": 19.4,
"dewPoint": 10.2,
"pressure": 1015,
"aqi": 2
}
}Autenticação
Requisições externas se autenticam por meio do cabeçalho x-api-key. Gere uma chave no seu painel — a chave bruta é exibida exatamente uma vez.
Cabeçalho
x-api-key: sp_live_YOUR_API_KEY_HEREEnvie sua chave de API no cabeçalho de requisição x-api-key em todas as chamadas.
Escopos
| Escopo | Descrição |
|---|---|
| predict:read | Ler previsões de pôr do sol (necessário para /api/predict) |
| usage:read | Ler as estatísticas de uso da própria chave (necessário para /api/usage) |
Limites
Plano gratuito — 100 requisições por dia por chave, redefinidas à meia-noite UTC.
Cabeçalhos de resposta do limite de requisições
Toda resposta autenticada bem-sucedida traz estes cabeçalhos para que você acompanhe a cota em tempo real:
| X-RateLimit-Limit | Número máximo de requisições permitidas na janela atual |
| X-RateLimit-Remaining | Requisições restantes hoje |
| X-RateLimit-Reset | Carimbo de data/hora ISO 8601 de quando a cota é redefinida |
| Retry-After | Segundos a aguardar antes de tentar novamente (apenas em 429) |
Exemplo de requisição autenticada
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Referência de Endpoint
Playground da API
Teste a API diretamente do seu navegador
Começa com sp_live_ e tem 40 caracteres
Armazenada apenas nesta aba do navegador (sessionStorage). Apagada ao fechar a aba.
Hoje até 5 dias à frente. Deixe vazio para hoje.
URL da Requisição
Exemplos de Código
Exemplos prontos para uso em linguagens populares
# Set your API key once (mint from /dashboard/api-keys)
export SUNSET_API_KEY="sp_live_YOUR_API_KEY_HERE"
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Os exemplos atualizam em tempo real conforme os parâmetros do playground.
Respostas de Erro
Respostas de erro comuns e seus significados
Requisição Inválida
Parâmetros ausentes ou inválidos. Forneça cidade ou lat/lon.
{
"error": "Either lat/lon or city must be provided"
}Não autorizado
Chave de API ausente, malformada ou revogada. Envie uma chave válida no cabeçalho x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Proibido
A chave é válida, mas não possui o escopo predict:read exigido para este endpoint.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Não Encontrado
A cidade especificada não pôde ser encontrada.
{
"error": "City not found",
"code": "cityNotFound"
}Requisições em excesso
Cota diária excedida (100 requisições/dia no plano gratuito). Redefinida à meia-noite UTC; verifique o cabeçalho Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Erro do Servidor
Ocorreu um erro interno do servidor. Por favor, tente novamente mais tarde.
{
"error": "Internal server error"
}Gateway inválido
O provedor de geocodificação upstream falhou. Tente novamente após um pequeno intervalo; considere enviar lat/lon para pular a geocodificação.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Melhores Práticas
Cache de respostas
As previsões são armazenadas em cache por 30 minutos. Evite consultar com mais frequência.
Intervalo de datas
As previsões estão disponíveis para hoje até 5 dias à frente. Datas mais distantes retornam resultados menos precisos.
Prefira coordenadas
Usar lat/lon é mais preciso e evita ambiguidade com nomes de cidades compartilhados entre regiões.
Trate erros graciosamente
Sempre verifique o código de status HTTP e trate respostas 400/404/500 adequadamente.
Respeite os limites de requisições
Leia X-RateLimit-Remaining em todas as respostas. Em caso de 429, aguarde a janela de Retry-After (redefinição à meia-noite UTC) antes de tentar novamente.
Mantenha as chaves no lado do servidor
Nunca incorpore uma chave de API em um pacote de cliente público, aplicativo móvel ou repositório. Faça proxy pelo seu backend e armazene as chaves em variáveis de ambiente ou em um gerenciador de segredos.
Uso e licenciamento
Quando o plano gratuito basta — e quando precisa de um plano pago.
Plano gratuito
Grátis para uso pessoal, hobby, casa inteligente e testes.
- •Projetos pessoais e protótipos
- •Hobby e aprendizado
- •Painéis de casa inteligente (ex.: Home Assistant) para uso pessoal
- •Testes e avaliação
100 pedidos/dia por chave API.
Plano Plus
Limites pessoais maiores e site sem anúncios. Apenas uso pessoal — projetos comerciais exigem Pro.
200 solicitações/dia por chave de API, 2 chaves de API.
Uso comercial
O uso comercial requer um plano pago — Pro ou Business.
Os planos pagos têm limites diários mais altos e permitem mais chaves API.
Ver preçosHome Assistant e outras integrações de casa inteligente continuam permitidas no plano gratuito para uso pessoal, não comercial.
Mantenha a sua chave API secreta. Use-a no servidor e nunca a inclua em código de cliente público nem a envie para um repositório.
Está construindo algo comercial ou esbarrou em um limite que não consegue resolver? Falar com o suporte