API waktu matahari terbit dan terbenam v2

API gratis kami memberi tahu Anda kapan matahari terbit dan terbenam di mana saja di Bumi, ditambah data senja, golden hour, posisi matahari, dan bulan. Anda hanya perlu lintang dan bujur: Anda membuat permintaan GET sederhana dan mendapatkan jawabannya sebagai JSON.

Waktu diberikan dalam zona waktu lokal tempat tersebut, dan Anda dapat meminta satu hari atau hingga satu tahun penuh dalam satu permintaan.

API ini gratis digunakan: tidak perlu pendaftaran atau kunci API. Namun kami mewajibkan atribusi: tampilkan tautan yang terlihat ke sunrise-sunset.org di aplikasi atau halaman tempat Anda menampilkan data.

Dokumentasi versi 1 API (/json) telah dipindahkan ke dokumentasi v1. API itu sendiri tidak berubah dan didukung selamanya.

Dokumentasi API

Buat permintaan GET ke https://api.sunrise-sunset.org/v2. Coba sekarang juga, tautan ini berfungsi di peramban Anda:

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

HTTP biasa juga didukung: berguna untuk IoT dan perangkat tertanam (Arduino, ESP8266, mikrokontroler) yang tidak dapat membuat koneksi TLS.

Contoh lain: tanggal tertentu, dan satu tahun penuh dalam satu permintaan:

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

Parameter permintaan

Respons

Semua waktu menggunakan format ISO 8601: 2026-01-15T08:27:43+01:00 berarti 15 Januari pukul 08:27:43 pagi, waktu setempat (1 jam di depan UTC). Setiap bahasa pemrograman memahaminya langsung; di JavaScript, new Date(data.sunrise) langsung berfungsi. Contoh respons:


    {
      "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
    }

Dengan date_start/date_end, responsnya adalah {"tzid", "lat", "lng", "days": […]} di mana setiap elemen days memiliki bidang di atas (tanpa tzid/lat/lng).

Definisi bidang

Apa arti setiap bidang, dengan kata-kata sederhana, dengan definisi tepat dalam tanda kurung (permintaan yang sama selalu mengembalikan waktu yang persis sama):

Lihat glosarium definisi astronomi kami untuk mempelajari lebih lanjut tentang setiap peristiwa.

Hari kutub dan nilai null

sun_status adalah normal, midnight_sun (matahari tidak pernah terbenam: day_length adalah 86400) atau polar_night (matahari tidak pernah terbit: day_length adalah 0). Peristiwa yang tidak terjadi adalah null. Semua peristiwa dapat bernilai null secara independen: dekat lingkaran kutub ada hari transisi di mana matahari terbit tetapi tidak terbenam dalam hari kalender; maka sunrise memiliki nilai, sunset adalah null, sun_status adalah normal dan day_length adalah null. Jangan pernah menyimpulkan satu peristiwa dari peristiwa lain.

Kesalahan

Jika ada yang salah dalam permintaan Anda, API memberi tahu Anda apa yang terjadi dan cara memperbaikinya, dengan kata-kata sederhana:


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

Untuk yang berorientasi teknis: kode status HTTP standar digunakan: 400 untuk input tidak valid, 404 untuk rute tidak dikenal, 429 saat Anda mengirim terlalu banyak permintaan terlalu cepat.

Batas penggunaan dan atribusi

API ini gratis untuk volume permintaan yang wajar. Kami mewajibkan Anda menampilkan atribusi kepada kami dengan tautan ke situs kami.

Jika Anda mengirim terlalu banyak permintaan terlalu cepat, API menjawab 429 ("pelan-pelan") dengan header Retry-After yang memberi tahu berapa detik harus menunggu sebelum mencoba lagi. Rentang tanggal dihitung sebagai satu permintaan, jadi jika Anda menampilkan data untuk tempat yang sama setiap hari, minta satu tahun penuh sekaligus dengan date_start/date_end: lebih cepat untuk Anda, lebih ringan untuk semua orang.

Tips lain agar tetap jauh di bawah batas: waktu untuk tanggal tertentu tidak pernah berubah, jadi simpan respons dan gunakan kembali alih-alih meminta lagi (peramban bahkan melakukannya secara otomatis dengan respons kami). (Detail teknis: tanggal eksplisit disajikan dengan Cache-Control: immutable, today/tomorrow dengan max-age hingga tengah malam lokal, dan ETag didukung.)

Menggunakan API dari halaman web (JavaScript)

Anda dapat memanggil API langsung dari halaman web Anda, tanpa server atau backend: permintaan dari situs mana pun diizinkan:

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);
  });

Bermigrasi dari v1

v1 (/json)v2 (/v2)
formatted=0 (ISO 8601)selalu ISO 8601, tidak perlu parameter
formatted=1 (12h AM/PM)dihapus
tzid=X (nilai tidak valid diam-diam kembali ke UTC)tz=X (nilai tidak valid mengembalikan HTTP 400 invalid_tz)
waktu bawaannya UTCwaktu bawaannya zona waktu lokal koordinat
callback (JSONP)dihapus (gunakan CORS)
kesalahan sebagai status: INVALID_*kesalahan sebagai {error, message, docs}
hari kutub: stempel waktu epoch-1970null + sun_status
lat=abc dihitung sebagai 0HTTP 400 invalid_lat
satu permintaan per haridate_start/date_end (hingga 366 hari)
n/agolden hour dan blue hour, azimut, ketinggian matahari

Pengumuman

Berlangganan buletin API kami untuk mendapatkan informasi terbaru tentang perubahan dan pengumuman layanan:

Catatan perubahan

Kontak

Silakan hubungi kami untuk semua pertanyaan API Anda.

Jika Anda senang menggunakan API kami, silakan pertimbangkan untuk mendukung proyek ini dengan membelikan kami kopi!