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-10-15
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:29:18+01:00",
      "sunset": "2026-01-15T18:25:09+01:00",
      "solar_noon": "2026-01-15T13:26:44+01:00",
      "day_length": 35751,
      "sun_status": "normal",
      "civil_twilight_begin": "2026-01-15T08:01:05+01:00",
      "civil_twilight_end": "2026-01-15T18:53:22+01:00",
      "nautical_twilight_begin": "2026-01-15T07:29:17+01:00",
      "nautical_twilight_end": "2026-01-15T19:25:11+01:00",
      "astronomical_twilight_begin": "2026-01-15T06:58:14+01:00",
      "astronomical_twilight_end": "2026-01-15T19:56:15+01:00",
      "dawn": "2026-01-15T08:01:05+01:00",
      "dusk": "2026-01-15T18:53:22+01:00",
      "first_light": "2026-01-15T06:58:14+01:00",
      "last_light": "2026-01-15T19:56:15+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:05+01:00",
          "end": "2026-01-15T08:11:54+01:00"
        },
        "evening": {
          "begin": "2026-01-15T18:42:33+01:00",
          "end": "2026-01-15T18:53:22+01:00"
        }
      },
      "solar_position": {
        "sunrise_azimuth": 116,
        "sunset_azimuth": 244.1,
        "solar_noon_azimuth": 179.9,
        "solar_noon_altitude": 32.22
      },
      "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).

Rentang bisa mengembalikan lebih sedikit hari daripada yang Anda minta. Ada hari kalender yang di sebagian tempat tidak pernah ada: Samoa melewati 30 Desember 2011 sepenuhnya saat melintasi garis penanggalan. Hari-hari itu tidak dimasukkan ke days, jadi cocokkan setiap entri lewat kolom date-nya, bukan dengan mengasumsikan satu per hari yang diminta.

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.

Akurasi perhitungan

Setiap peristiwa matahari adalah saat pusat Matahari melintasi ketinggian tertentu di atas cakrawala — −0,833° untuk terbit dan terbenam, serta −6°, −12° dan −18° untuk ketiga senja — dan selalu merupakan perlintasan yang terjadi di dalam hari kalender lokal yang Anda minta.

Waktu-waktu ini tidak sama dengan di versi 1 dari API ini. Versi lama itu mempertahankan perhitungan aslinya agar kode yang sudah ada tidak rusak: matahari terbitnya sedikit terlalu awal dan matahari terbenamnya sedikit terlalu lambat, hingga beberapa menit tergantung lokasi dan tanggal, dan waktu senjanya juga sedikit meleset, beberapa detik di dekat khatulistiwa dan hingga sekitar satu menit di lintang tinggi.

Kami telah membandingkan versi ini dengan acuan astronomi independen, efemeris planet JPL, untuk kota-kota dari khatulistiwa hingga Arktik selama satu tahun penuh: matahari terbit, matahari terbenam, dan ketiga senja hanya berselisih beberapa detik, dan sekitar setengah menit pada hari-hari dekat lingkaran kutub ketika matahari nyaris tidak melewati ambangnya. Waktu di situs web kami dihitung dengan cara yang sama.

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 jumlah permintaan yang wajar. Atribusi wajib. Sebutkan Sunrise-Sunset.org di mana pun orang dapat melihat asal data:

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:

Dapatkan pemberitahuan setiap ada perubahan: di GitHub, buka repositori API kami dan pilih Watch → Custom → Releases, atau ikuti feed RSS kami.

Catatan perubahan

Kontak

Silakan hubungi kami untuk semua pertanyaan API Anda.

If you enjoy using our API please consider supporting the project by buying us a coffee!