API Dokümantasyonu

Gün batımı kalitesi tahminlerini uygulamalarınıza entegre edin

Kullanımınızı takip etmek için bir API anahtarı alın

Temel URLhttps://sunset-predictor.com

Hızlı Başlangıç

Saniyeler içinde gün batımı tahmini alın

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

$SUNSET_API_KEY değerini panelinizdeki bir anahtarla değiştirin. Kimlik doğrulamasız çağrılar hızlı denemeler için çalışır, ancak daha sıkı sınırlara tabidir ve hız sınırı başlıklarını döndürmez.

Örnek Yanıt

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

Kimlik Doğrulama

Harici istekler x-api-key başlığı ile kimlik doğrular. Panelinizden bir anahtar oluşturun — ham anahtar yalnızca bir kez gösterilir.

Başlık

x-api-key: sp_live_YOUR_API_KEY_HERE

API anahtarınızı her çağrıda x-api-key istek başlığında gönderin.

Kapsamlar

Kapsam	Açıklama
predict:read	Gün batımı tahminlerini okuma (/api/predict için gerekli)
usage:read	Bu anahtarın kendi kullanım istatistiklerini okuma (/api/usage için gerekli)

Sınırlar

Ücretsiz katman — anahtar başına günde 100 istek, UTC gece yarısı sıfırlanır.

Hız sınırı yanıt başlıkları

Kimliği doğrulanmış her başarılı yanıt, kotayı gerçek zamanlı takip edebilmeniz için şu başlıkları içerir:

X-RateLimit-Limit	Geçerli zaman aralığında izin verilen en fazla istek sayısı
X-RateLimit-Remaining	Bugün kalan istekler
X-RateLimit-Reset	Kotanın sıfırlanacağı anın ISO 8601 zaman damgası
Retry-After	Yeniden denemeden önce beklenecek saniye (yalnızca 429'da)

Kimliği doğrulanmış örnek istek

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

Uç Nokta Referansı

API Deneme Alanı

API'yi doğrudan tarayıcınızdan test edin. Kimliği doğrulanmış bir çağrı yapmak için API anahtarınızı yapıştırın (günlük kotanızdan düşülür); kimlik doğrulamasız bir demo çağrısı için boş bırakın.

Uç nokta

API Anahtarı (isteğe bağlı)Anahtar alın →

sp_live_ ile başlar ve 40 karakter uzunluğundadır

Yalnızca bu tarayıcı sekmesinde (sessionStorage) saklanır. Sekmeyi kapattığınızda silinir.

Şehir

Enlem

Boylam

Tarih

Bugünden 5 gün sonrasına kadar. Bugün için boş bırakın.

Dil

Birimler

İstek URL'si

GET /api/v1/predict?city=Paris

Kod Örnekleri

Popüler dillerde kullanıma hazır örnekler

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

Yukarıdaki deneme alanı parametrelerini değiştirdikçe kod parçacıkları anında güncellenir.

Hata Yanıtları

Sık karşılaşılan hata yanıtları ve anlamları

400İstemci hatası

Hatalı İstek

Eksik veya geçersiz parametreler. city ya da lat/lon belirtin.

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

401Kimlik doğrulama / izin

Yetkisiz

API anahtarı eksik, hatalı biçimli veya iptal edilmiş. x-api-key başlığında geçerli bir anahtar gönderin.

{
  "error": "Invalid or revoked API key",
  "code": "unauthorized"
}

403Kimlik doğrulama / izin

Erişim Engellendi

Anahtar geçerli, ancak bu uç nokta için gereken predict:read kapsamına sahip değil.

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

404İstemci hatası

Bulunamadı

Belirtilen şehir bulunamadı.

{
  "error": "City not found",
  "code": "cityNotFound"
}

429İstemci hatası

Çok Fazla İstek

Günlük kota aşıldı (ücretsiz katmanda günde 100 istek). UTC gece yarısı sıfırlanır; Retry-After başlığını kontrol edin.

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

500Sunucu hatası

Sunucu Hatası

Dahili bir sunucu hatası oluştu. Lütfen daha sonra tekrar deneyin.

{
  "error": "Internal server error"
}

502Sunucu hatası

Hatalı Ağ Geçidi

Harici coğrafi kodlama sağlayıcısında hata oluştu. Kısa bir gecikmeyle yeniden deneyin; coğrafi kodlamayı atlamak için lat/lon göndermeyi düşünün.

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

En İyi Uygulamalar

Yanıtları önbelleğe alın

Tahminler sunucu tarafında her (lat, lon, lang, date) için 20 dakika önbelleğe alınır. Daha sık sorgulamaktan kaçının.

Tarih aralığı

Tahminler dünden 5 gün sonrasına kadar kullanılabilir. Daha ileri tarihler daha az doğru sonuçlar döndürür.

Koordinatları tercih edin

lat/lon kullanmak daha kesindir, farklı bölgelerde aynı adı taşıyan şehirlerle karışıklığı önler ve coğrafi kodlamayı atlar.

Hataları düzgün yönetin

HTTP durum kodunu ve yanıttaki code alanını kontrol edin. 401/403 hatalarını kullanıcıya gösterin, 429 alırsanız Retry-After değerine göre bekleyin.

Hız sınırlarına uyun

Her yanıtta X-RateLimit-Remaining değerini okuyun. 429 alırsanız yeniden denemeden önce Retry-After süresini (UTC gece yarısı sıfırlama) bekleyin.

Anahtarları sunucu tarafında tutun

API anahtarını asla herkese açık bir istemci paketine, mobil uygulamaya veya depoya yerleştirmeyin. İstekleri kendi arka ucunuz üzerinden yönlendirin ve anahtarları ortam değişkenlerinde veya bir gizli anahtar yöneticisinde saklayın.

Kullanım ve Lisanslama

Ücretsiz katman ne zaman yeterli, ne zaman ücretli bir plan gerekir?

Ücretsiz katman

Kişisel, hobi, akıllı ev ve test amaçlı kullanım için ücretsiz.

•Kişisel projeler ve prototipler
•Hobi ve öğrenme
•Kişisel kullanım için akıllı ev panelleri (ör. Home Assistant)
•Test ve değerlendirme

API anahtarı başına günde 100 istek.

Plus katmanı

Destekçiler için daha yüksek kişisel sınırlar ve reklamsız site. Yalnızca kişisel kullanım içindir — ticari projeler için Pro gerekir.

API anahtarı başına günde 200 istek, 2 API anahtarı.

Ticari kullanım

Ticari kullanım için ücretli bir plan gerekir — Pro veya Business.

Ücretli katmanlar daha yüksek günlük istek sınırları sunar ve daha fazla API anahtarına izin verir.

Fiyatları görüntüle

Home Assistant ve diğer akıllı ev entegrasyonları, kişisel ve ticari olmayan kullanım için ücretsiz katmanda kullanılmaya devam edebilir.

API anahtarınızı gizli tutun. Sunucu tarafında kullanın; asla herkese açık istemci tarafı koda yerleştirmeyin veya bir depoya commit etmeyin.

Ticari bir şey mi geliştiriyorsunuz ya da aşamadığınız bir sınıra mı takıldınız? Destekle iletişime geçin