Documentación de la API
Integra predicciones de calidad del atardecer en tus aplicaciones
Obtén una clave API para rastrear tu usoInicio rápido
Obtén una predicción de atardecer en segundos
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Sustituya $SUNSET_API_KEY por una clave de su panel. Las llamadas sin autenticar funcionan para demos rápidas pero son más estrictas y omiten los encabezados de límite.
Ejemplo de respuesta
{
"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
}
}Autenticación
Las peticiones externas se autentican mediante la cabecera x-api-key. Genera una clave desde tu panel de control: la clave sin procesar se muestra exactamente una vez.
Cabecera
x-api-key: sp_live_YOUR_API_KEY_HEREEnvía tu clave de API en la cabecera de petición x-api-key en cada llamada.
Ámbitos
| Ámbito | Descripción |
|---|---|
| predict:read | Leer predicciones de puesta de sol (requerido para /api/predict) |
| usage:read | Leer las estadísticas de uso de esta misma clave (requerido para /api/usage) |
Límites
Nivel gratuito: 100 peticiones por día por clave, restablecido a medianoche UTC.
Cabeceras de respuesta del límite de peticiones
Cada respuesta autenticada correcta incluye estas cabeceras para que puedas controlar la cuota en tiempo real:
| X-RateLimit-Limit | Máximo de peticiones permitidas en la ventana actual |
| X-RateLimit-Remaining | Peticiones restantes hoy |
| X-RateLimit-Reset | Marca de tiempo ISO 8601 de cuándo se restablece la cuota |
| Retry-After | Segundos de espera antes de reintentar (solo en 429) |
Ejemplo de petición autenticada
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Referencia de endpoints
Playground de la API
Prueba la API directamente desde tu navegador
Comienza por sp_live_ y tiene 40 caracteres de longitud
Se almacena solo en esta pestaña del navegador (sessionStorage). Se borra al cerrar la pestaña.
Hoy hasta 5 días después. Dejar vacío para hoy.
URL de la solicitud
Ejemplos de código
Ejemplos listos para usar en lenguajes 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"Los ejemplos se actualizan en vivo según los parámetros del playground.
Respuestas de error
Errores comunes y su significado
Solicitud inválida
Parámetros faltantes o inválidos. Proporciona ciudad o lat/lon.
{
"error": "Either lat/lon or city must be provided"
}No autorizado
Clave de API ausente, mal formada o revocada. Envía una clave válida en la cabecera x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Prohibido
La clave es válida pero carece del ámbito predict:read requerido para este endpoint.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}No encontrado
No se pudo encontrar la ciudad especificada.
{
"error": "City not found",
"code": "cityNotFound"
}Demasiadas peticiones
Cuota diaria superada (100 peticiones/día en el nivel gratuito). Se restablece a medianoche UTC; consulta la cabecera Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Error del servidor
Ocurrió un error interno del servidor. Por favor, inténtalo de nuevo más tarde.
{
"error": "Internal server error"
}Puerta de enlace incorrecta
El proveedor de geocodificación ascendente falló. Reintenta con un ligero retraso; considera enviar lat/lon para omitir la geocodificación.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Buenas prácticas
Almacena respuestas en caché
Las predicciones se almacenan en caché durante 30 minutos. Evita consultas más frecuentes.
Rango de fechas
Las predicciones están disponibles para hoy hasta 5 días adelante. Fechas más lejanas son menos precisas.
Prefiere coordenadas
Usar lat/lon es más preciso y evita la ambigüedad de nombres de ciudades compartidos.
Maneja los errores correctamente
Siempre verifica el código HTTP y maneja las respuestas 400/404/500 apropiadamente.
Respeta los límites de peticiones
Lee X-RateLimit-Remaining en cada respuesta. En un 429, espera la ventana de Retry-After (restablecimiento a medianoche UTC) antes de reintentar.
Mantén las claves en el servidor
Nunca incrustes una clave de API en un paquete de cliente público, una aplicación móvil o un repositorio. Redirígela a través de tu backend y guarda las claves en variables de entorno o en un gestor de secretos.
Uso y licencia
Cuándo basta el plan gratuito — y cuándo necesitas un plan de pago.
Plan gratuito
Gratis para uso personal, hobby, hogar inteligente y pruebas.
- •Proyectos personales y prototipos
- •Afición y aprendizaje
- •Paneles de domótica (p. ej. Home Assistant) para uso personal
- •Pruebas y evaluación
100 solicitudes/día por clave API.
Plan Plus
Límites personales más altos y un sitio sin anuncios. Solo uso personal: los proyectos comerciales necesitan Pro.
200 solicitudes/día por clave API, 2 claves API.
Uso comercial
El uso comercial requiere un plan de pago — Pro o Business.
Los planes de pago tienen límites diarios más altos y permiten más claves API.
Ver preciosHome Assistant y otras integraciones de hogar inteligente siguen permitidas en el plan gratuito para uso personal, no comercial.
Mantén tu clave API en secreto. Úsala en el servidor y nunca la incluyas en código de cliente público ni la subas a un repositorio.
¿Estás montando algo comercial o has chocado con un límite? Contactar con soporte