Langsung ke konten

Dokumentasi API

Integrasikan prediksi kualitas matahari terbenam ke dalam aplikasi Anda

Dapatkan kunci API untuk memantau penggunaan Anda
URL Dasarhttps://sunset-predictor.com
Spesifikasi OpenAPI

Mulai Cepat

Dapatkan prediksi matahari terbenam dalam hitungan detik

curl -H "x-api-key: $SUNSET_API_KEY" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

Ganti $SUNSET_API_KEY dengan kunci dari dasbor Anda. Panggilan tanpa autentikasi dapat digunakan untuk demo singkat, tetapi lebih ketat dan tidak menyertakan header batas laju.

Contoh Respons

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

Autentikasi

Permintaan eksternal diautentikasi melalui header x-api-key. Buat kunci dari dasbor Anda — kunci asli hanya ditampilkan satu kali.

Header

x-api-key: sp_live_YOUR_API_KEY_HERE

Kirim kunci API Anda pada header permintaan x-api-key di setiap panggilan.

Scope

ScopeDeskripsi
predict:readMembaca prediksi matahari terbenam (diperlukan untuk /api/predict)
usage:readMembaca statistik penggunaan kunci ini sendiri (diperlukan untuk /api/usage)

Batas

Paket Free — 100 permintaan per hari untuk setiap kunci, direset pada tengah malam UTC.

Header respons batas laju

Setiap respons terautentikasi yang berhasil menyertakan header berikut sehingga Anda dapat memantau kuota secara real time:

X-RateLimit-LimitJumlah maksimum permintaan yang diizinkan pada jendela saat ini
X-RateLimit-RemainingSisa permintaan hari ini
X-RateLimit-ResetStempel waktu ISO 8601 saat kuota direset
Retry-AfterDetik yang harus ditunggu sebelum mencoba lagi (hanya pada 429)

Contoh permintaan terautentikasi

curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

Referensi Endpoint

Playground API

Uji API langsung dari browser Anda. Tempel kunci API Anda untuk melakukan panggilan terautentikasi (dihitung terhadap kuota harian Anda); kosongkan untuk melakukan panggilan demo tanpa autentikasi.

Dapatkan kunci →

Diawali dengan sp_live_ dan panjangnya 40 karakter

Disimpan hanya di tab browser ini (sessionStorage). Dihapus saat Anda menutup tab.

Dari hari ini hingga 5 hari ke depan. Kosongkan untuk hari ini.

URL Permintaan

GET /api/v1/predict?city=Paris

Contoh Kode

Contoh siap pakai dalam bahasa pemrograman populer

# 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"

Cuplikan kode diperbarui secara langsung saat Anda mengubah parameter playground di atas.

Respons Kesalahan

Respons kesalahan umum beserta artinya

400Kesalahan klien

Permintaan Tidak Valid

Parameter hilang atau tidak valid. Sertakan city atau lat/lon.

{
  "error": "Either lat/lon or city must be provided"
}
401Autentikasi / izin

Tidak Diizinkan

Kunci API hilang, salah format, atau telah dicabut. Kirim kunci yang valid pada header x-api-key.

{
  "error": "Invalid or revoked API key",
  "code": "unauthorized"
}
403Autentikasi / izin

Dilarang

Kunci valid tetapi tidak memiliki scope predict:read yang diperlukan untuk endpoint ini.

{
  "error": "Insufficient permissions. Required scope: predict:read",
  "code": "insufficientScope"
}
404Kesalahan klien

Tidak Ditemukan

Kota yang ditentukan tidak ditemukan.

{
  "error": "City not found",
  "code": "cityNotFound"
}
429Kesalahan klien

Terlalu Banyak Permintaan

Kuota harian terlampaui (100 permintaan/hari pada paket Free). Direset pada tengah malam UTC; periksa header Retry-After.

{
  "error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
  "code": "rateLimitExceeded",
  "retryAfter": 3600
}
500Kesalahan server

Kesalahan Server

Terjadi kesalahan server internal. Silakan coba lagi nanti.

{
  "error": "Internal server error"
}
502Kesalahan server

Gateway Buruk

Penyedia geokode hulu gagal. Coba lagi setelah jeda singkat; pertimbangkan mengirim lat/lon untuk melewati geokode.

{
  "error": "Unable to look up city location",
  "code": "geocodingFailed"
}

Praktik Terbaik

Cache respons

Prediksi di-cache di sisi server selama 20 menit untuk setiap (lat, lon, lang, date). Hindari polling yang lebih sering.

Rentang tanggal

Prediksi tersedia dari kemarin hingga 5 hari ke depan. Tanggal yang lebih jauh menghasilkan hasil yang kurang akurat.

Utamakan koordinat

Menggunakan lat/lon lebih presisi, menghindari ambiguitas nama kota yang sama di beberapa wilayah, dan melewati geokode.

Tangani kesalahan dengan baik

Periksa kode status HTTP dan field code pada respons. Tampilkan 401/403 kepada pengguna dan kurangi laju pada 429 menggunakan Retry-After.

Patuhi batas laju

Baca X-RateLimit-Remaining pada setiap respons. Pada 429, tunggu hingga jendela Retry-After (reset tengah malam UTC) sebelum mencoba lagi.

Simpan kunci di sisi server

Jangan pernah menyematkan kunci API dalam bundel klien publik, aplikasi seluler, atau repositori. Gunakan proxy melalui backend Anda dan simpan kunci di variabel lingkungan atau secret manager.

Penggunaan & Lisensi

Kapan paket Free sudah cukup — dan kapan Anda memerlukan paket berbayar.

Paket Free

Gratis untuk penggunaan pribadi, hobi, rumah pintar, dan pengujian.

  • •Proyek pribadi dan prototipe
  • •Hobi dan belajar
  • •Dasbor rumah pintar (mis. Home Assistant) untuk penggunaan pribadi
  • •Pengujian dan evaluasi

100 permintaan/hari per kunci API.

Paket Plus

Batas pribadi yang lebih tinggi bagi pendukung, plus situs bebas iklan. Hanya untuk penggunaan pribadi — proyek komersial memerlukan Pro.

200 permintaan/hari per kunci API, 2 kunci API.

Penggunaan komersial

Penggunaan komersial memerlukan paket berbayar — Pro atau Business.

Paket berbayar memiliki batas permintaan harian yang lebih tinggi dan mengizinkan lebih banyak kunci API.

Lihat harga

Home Assistant dan integrasi rumah pintar lainnya tetap diizinkan pada paket Free untuk penggunaan pribadi non-komersial.

Jaga kerahasiaan kunci API Anda. Gunakan di sisi server dan jangan pernah menyematkannya dalam kode klien publik atau meng-commit-nya ke repositori.

Membangun sesuatu yang komersial atau mencapai batas yang tidak dapat Anda atasi? Hubungi dukungan