API des heures de lever et de coucher du soleil v2

Notre API gratuite vous indique quand le soleil se lève et se couche partout sur Terre, ainsi que les données de crépuscule, heure dorée, position solaire et lune. Il vous suffit d'une latitude et d'une longitude : vous faites une simple requête GET et obtenez la réponse en JSON.

Les heures sont fournies dans le fuseau horaire local du lieu, et vous pouvez demander un seul jour ou jusqu'à une année entière en une seule requête.

L'API est gratuite : ni inscription ni clé requise. Nous exigeons en revanche une attribution : affichez un lien visible vers sunrise-sunset.org dans l'application ou la page où vous affichez les données.

La documentation de la version 1 de l'API (/json) a été déplacée vers la documentation v1. L'API elle-même reste inchangée et prise en charge pour toujours.

Documentation de l’API

Faites une requête GET vers https://api.sunrise-sunset.org/v2. Essayez tout de suite, ce lien fonctionne dans votre navigateur :

https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400

Le HTTP simple est également pris en charge : pratique pour l'IoT et les appareils embarqués (Arduino, ESP8266, microcontrôleurs) qui ne peuvent pas établir de connexions TLS.

Plus d'exemples : une date précise, et une année entière en une seule requête :

https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400&date=2026-07-12
https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400&date_start=2026-01-01&date_end=2026-12-31

Paramètres de la demande

Réponse

Toutes les heures utilisent le format ISO 8601 : 2026-01-15T08:27:43+01:00 signifie le 15 janvier à 08:27:43 du matin, heure locale (1 heure en avance sur UTC). Tous les langages de programmation le comprennent d'emblée ; en JavaScript, new Date(data.sunrise) fonctionne directement. Un exemple de réponse :


    {
      "date": "2026-01-15",
      "tzid": "Europe/Madrid",
      "utc_offset": "+01:00",
      "lat": 36.7202,
      "lng": -4.4203,
      "sunrise": "2026-01-15T08:27:43+01:00",
      "sunset": "2026-01-15T18:26:27+01:00",
      "solar_noon": "2026-01-15T13:27:05+01:00",
      "day_length": 35924,
      "sun_status": "normal",
      "civil_twilight_begin": "2026-01-15T08:01:01+01:00",
      "civil_twilight_end": "2026-01-15T18:53:09+01:00",
      "nautical_twilight_begin": "2026-01-15T07:29:13+01:00",
      "nautical_twilight_end": "2026-01-15T19:24:57+01:00",
      "astronomical_twilight_begin": "2026-01-15T06:58:10+01:00",
      "astronomical_twilight_end": "2026-01-15T19:56:00+01:00",
      "dawn": "2026-01-15T08:01:01+01:00",
      "dusk": "2026-01-15T18:53:09+01:00",
      "first_light": "2026-01-15T07:29:13+01:00",
      "last_light": "2026-01-15T19:24:57+01:00",
      "golden_hour": {
        "morning": { "begin": "2026-01-15T08:11:54+01:00", "end": "2026-01-15T09:08:17+01:00" },
        "evening": { "begin": "2026-01-15T17:46:10+01:00", "end": "2026-01-15T18:42:33+01:00" }
      },
      "blue_hour": {
        "morning": { "begin": "2026-01-15T08:01:01+01:00", "end": "2026-01-15T08:11:54+01:00" },
        "evening": { "begin": "2026-01-15T18:42:33+01:00", "end": "2026-01-15T18:53:09+01:00" }
      },
      "solar_position": {
        "sunrise_azimuth": 118.31,
        "sunset_azimuth": 241.82,
        "solar_noon_azimuth": 180.09,
        "solar_noon_altitude": 32.06
      },
      "moonrise": "2026-01-15T06:01:54+01:00",
      "moonset": "2026-01-15T15:14:23+01:00",
      "moon_phase": "Waning Crescent",
      "moon_illumination": 10.62
    }

Avec date_start/date_end, la réponse est {"tzid", "lat", "lng", "days": […]} où chaque élément de days a les champs ci-dessus (moins tzid/lat/lng).

Définition des champs

Ce que signifie chaque champ, en mots simples, avec la définition exacte entre parenthèses (la même requête renvoie toujours exactement les mêmes heures) :

Consultez notre glossaire des définitions astronomiques pour en savoir plus sur chaque événement.

Jours polaires et valeurs nulles

sun_status vaut normal, midnight_sun (le soleil ne se couche jamais : day_length vaut 86400) ou polar_night (le soleil ne se lève jamais : day_length vaut 0). Les événements qui n'ont pas lieu valent null. Tous les événements sont nuls de façon indépendante : près des cercles polaires il y a des jours de transition où le soleil se lève mais ne se couche pas dans le jour calendaire ; alors sunrise a une valeur, sunset vaut null, sun_status vaut normal et day_length vaut null. Ne déduisez jamais un événement d'un autre.

Erreurs

Si quelque chose ne va pas dans votre requête, l'API vous dit ce qui s'est passé et comment le corriger, en mots simples :


    {
      "error": "invalid_tz",
      "message": "Unknown tz 'PST'. Use IANA identifiers like 'America/Los_Angeles'.",
      "docs": "https://sunrise-sunset.org/api#tz"
    }

Pour les plus techniques : des codes de statut HTTP standard sont utilisés : 400 pour une entrée invalide, 404 pour les routes inconnues, 429 quand vous envoyez trop de requêtes trop vite.

Limites d'utilisation et attribution

L'API est gratuite pour des volumes de requêtes raisonnables. Nous exigeons que vous affichiez une attribution vers nous avec un lien vers notre site.

Si vous envoyez trop de requêtes trop vite, l'API répond 429 (« ralentissez ») avec un en-tête Retry-After indiquant combien de secondes attendre avant de réessayer. Une plage de dates compte comme une seule requête, donc si vous affichez les données du même lieu chaque jour, demandez l'année entière en une fois avec date_start/date_end : plus rapide pour vous, plus léger pour tous.

Autre astuce pour rester bien en dessous des limites : les heures d'une date donnée ne changent jamais, alors enregistrez la réponse et réutilisez-la au lieu de redemander (les navigateurs le font même automatiquement avec nos réponses). (Détails techniques : les dates explicites sont servies avec Cache-Control: immutable, today/tomorrow avec max-age jusqu'à minuit local, et ETag est pris en charge.)

Utiliser l'API depuis une page web (JavaScript)

Vous pouvez appeler l'API directement depuis votre page web, sans serveur ni backend : les requêtes depuis n'importe quel site sont autorisées :

fetch('https://api.sunrise-sunset.org/v2?lat=36.72&lng=-4.42')
  .then(response => response.json())
  .then(data => {
    console.log('Sunrise:', data.sunrise);
    console.log('Sunset:', data.sunset);
  });

Migrer depuis la v1

v1 (/json)v2 (/v2)
formatted=0 (ISO 8601)toujours ISO 8601, aucun paramètre nécessaire
formatted=1 (12h AM/PM)supprimé
tzid=X (les valeurs invalides basculent silencieusement sur UTC)tz=X (les valeurs invalides renvoient HTTP 400 invalid_tz)
les heures sont en UTC par défautles heures sont par défaut dans le fuseau horaire local des coordonnées
callback (JSONP)supprimé (utilisez CORS)
erreurs sous forme status: INVALID_*erreurs sous forme {error, message, docs}
jours polaires : horodatages epoch-1970null + sun_status
lat=abc calculé comme 0HTTP 400 invalid_lat
une requête par jourdate_start/date_end (jusqu'à 366 jours)
n/aheure dorée et bleue, azimut, altitude solaire

Annonces

S'abonner à notre lettre d'information sur l'API pour être tenu au courant des changements et des annonces concernant le service :

Changelog

Contact

N'hésitez pas à nous contacter pour toutes vos questions relatives à l'API.

Si vous aimez utiliser notre API, n'hésitez pas à soutenir le projet en nous offrant un café !