Documentation API
Intégrez les prédictions de qualité de coucher de soleil dans vos applications
Obtenez une clé API pour suivre votre utilisationDémarrage rapide
Obtenez une prédiction de coucher de soleil en quelques secondes
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Remplacez $SUNSET_API_KEY par une clé de votre tableau de bord. Les appels non authentifiés fonctionnent pour les démos rapides mais sont plus stricts et n’incluent pas les en-têtes de limitation.
Exemple de réponse
{
"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
}
}Authentification
Les requêtes externes s'authentifient via l'en-tête x-api-key. Générez une clé depuis votre tableau de bord — la clé brute n'est affichée qu'une seule fois.
En-tête
x-api-key: sp_live_YOUR_API_KEY_HEREEnvoyez votre clé API dans l'en-tête de requête x-api-key à chaque appel.
Scopes
| Scope | Description |
|---|---|
| predict:read | Lire les prévisions de coucher de soleil (requis pour /api/predict) |
| usage:read | Lire les statistiques d'utilisation propres à cette clé (requis pour /api/usage) |
Limites
Offre gratuite — 100 requêtes par jour et par clé, réinitialisées à minuit UTC.
En-têtes de réponse de limitation de débit
Chaque réponse authentifiée réussie comporte ces en-têtes afin que vous puissiez suivre votre quota en temps réel :
| X-RateLimit-Limit | Nombre maximal de requêtes autorisées dans la fenêtre en cours |
| X-RateLimit-Remaining | Requêtes restantes aujourd'hui |
| X-RateLimit-Reset | Horodatage ISO 8601 de réinitialisation du quota |
| Retry-After | Secondes à attendre avant de réessayer (uniquement en cas de 429) |
Exemple de requête authentifiée
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Référence des endpoints
Bac à sable API
Testez l'API directement depuis votre navigateur
Commence par sp_live_ et comporte 40 caractères
Stockée uniquement dans cet onglet du navigateur (sessionStorage). Effacée lorsque vous fermez l'onglet.
Aujourd’hui jusqu’à 5 jours. Laisser vide pour aujourd’hui.
URL de la requête
Exemples de code
Exemples prêts à l'emploi dans les langages populaires
# 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"Les exemples s’adaptent en direct aux paramètres du playground ci-dessus.
Réponses d'erreur
Erreurs courantes et leur signification
Requête invalide
Paramètres manquants ou invalides. Fournissez un ville ou lat/lon.
{
"error": "Either lat/lon or city must be provided"
}Non autorisé
Clé API manquante, mal formée ou révoquée. Envoyez une clé valide dans l'en-tête x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Interdit
La clé est valide mais ne dispose pas du scope predict:read requis pour ce point de terminaison.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Non trouvé
La ville spécifiée n'a pas été trouvée.
{
"error": "City not found",
"code": "cityNotFound"
}Trop de requêtes
Quota quotidien dépassé (100 requêtes/jour sur l'offre gratuite). Réinitialisation à minuit UTC ; consultez l'en-tête Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Erreur serveur
Une erreur interne du serveur s'est produite. Veuillez réessayer plus tard.
{
"error": "Internal server error"
}Mauvaise passerelle
Le fournisseur de géocodage en amont a échoué. Réessayez avec un léger délai ; envisagez d'envoyer lat/lon pour ignorer le géocodage.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Bonnes pratiques
Mettez en cache les réponses
Les prédictions sont mises en cache pendant 30 minutes. Évitez de faire des requêtes plus fréquentes.
Plage de dates
Les prédictions sont disponibles pour aujourd'hui jusqu'à 5 jours à l'avance. Les dates plus lointaines sont moins précises.
Préférez les coordonnées
L'utilisation de lat/lon est plus précise et évite l'ambiguïté des noms de villes partagés.
Gérez les erreurs
Vérifiez toujours le code HTTP et gérez les réponses 400/404/500 de manière appropriée.
Respectez les limites de débit
Lisez X-RateLimit-Remaining à chaque réponse. En cas de 429, attendez la fenêtre Retry-After (réinitialisation à minuit UTC) avant de réessayer.
Conservez les clés côté serveur
N'intégrez jamais une clé API dans un bundle client public, une application mobile ou un dépôt. Faites transiter les requêtes par votre backend et stockez les clés dans des variables d'environnement ou un gestionnaire de secrets.
Utilisation et licence
Quand le plan gratuit suffit — et quand un plan payant est nécessaire.
Plan gratuit
Gratuit pour un usage personnel, loisir, domotique et de test.
- •Projets personnels et prototypes
- •Loisir et apprentissage
- •Tableaux de bord domotiques (p. ex. Home Assistant) pour un usage personnel
- •Tests et évaluation
100 requêtes/jour par clé API.
Offre Plus
Des limites personnelles plus élevées et un site sans publicité. Usage personnel uniquement — les projets commerciaux nécessitent Pro.
200 requêtes/jour par clé API, 2 clés API.
Usage commercial
L’usage commercial nécessite un plan payant — Pro ou Business.
Les plans payants offrent des limites quotidiennes plus élevées et plus de clés API.
Voir les tarifsHome Assistant et autres intégrations domotiques restent autorisés sur le plan gratuit pour un usage personnel, non commercial.
Gardez votre clé API secrète. Utilisez-la côté serveur et ne l’intégrez jamais dans du code client public ni dans un dépôt.
Vous lancez un projet commercial ou butez sur une limite ? Contacter l'assistance