सामग्री पर जाएँ

API दस्तावेज़ीकरण

अपने एप्लिकेशन में सूर्यास्त गुणवत्ता भविष्यवाणियाँ एकीकृत करें

अपने उपयोग को ट्रैक करने के लिए एक API कुंजी प्राप्त करें
बेस URLhttps://sunset-predictor.com
OpenAPI स्पेक

क्विक स्टार्ट

सेकंड में सूर्यास्त भविष्यवाणी प्राप्त करें

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

$SUNSET_API_KEY को अपने डैशबोर्ड से एक कुंजी से बदलें। बिना प्रमाणीकरण वाली कॉल त्वरित डेमो के लिए काम करती हैं, लेकिन अधिक सख्त हैं और rate-limit हेडर नहीं भेजतीं।

उदाहरण प्रतिक्रिया

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

Authentication

बाहरी requests x-api-key header के माध्यम से authenticate होती हैं। अपने dashboard से एक key बनाएं — raw key केवल एक बार ही दिखाई जाती है।

Header

x-api-key: sp_live_YOUR_API_KEY_HERE

हर कॉल पर अपनी API key को x-api-key request header में भेजें।

Scopes

Scopeविवरण
predict:readसूर्यास्त की भविष्यवाणियाँ पढ़ें (/api/predict के लिए आवश्यक)
usage:readइस key के अपने उपयोग आँकड़े पढ़ें (/api/usage के लिए आवश्यक)

सीमाएँ

Free tier — प्रति key प्रति दिन 100 requests, UTC आधी रात को रीसेट होती हैं।

Rate-limit response headers

हर सफल authenticated response में ये headers होते हैं ताकि आप रियल टाइम में quota ट्रैक कर सकें:

X-RateLimit-Limitवर्तमान window में अनुमत अधिकतम requests
X-RateLimit-Remainingआज शेष बची requests
X-RateLimit-ResetISO 8601 timestamp जब quota रीसेट होती है
Retry-Afterपुनः प्रयास करने से पहले प्रतीक्षा करने के सेकंड (केवल 429 पर)

उदाहरण authenticated request

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

एंडपॉइंट संदर्भ

API प्लेग्राउंड

अपने ब्राउज़र से सीधे API का परीक्षण करें

एक कुंजी प्राप्त करें →

sp_live_ से शुरू होती है और 40 characters लंबी होती है

केवल इस browser tab में संग्रहीत (sessionStorage)। tab बंद करने पर साफ़ हो जाती है।

आज से 5 दिन तक। आज के लिए खाली छोड़ें।

अनुरोध URL

GET /api/v1/predict?city=Paris

कोड उदाहरण

लोकप्रिय भाषाओं में उपयोग-के-लिए-तैयार उदाहरण

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

उदाहरण ऊपर के playground पैरामीटर के साथ रीयल-टाइम अपडेट होते हैं।

त्रुटि प्रतिक्रियाएं

सामान्य त्रुटि प्रतिक्रियाएं और उनके अर्थ

400क्लाइंट त्रुटि

खराब अनुरोध

गुम या अमान्य पैरामीटर। शहर या lat/lon प्रदान करें।

{
  "error": "Either lat/lon or city must be provided"
}
401प्रमाणीकरण / अनुमति

Unauthorized

अनुपस्थित, विकृत, या निरस्त की गई API key। x-api-key header में एक वैध key भेजें।

{
  "error": "Invalid or revoked API key",
  "code": "unauthorized"
}
403प्रमाणीकरण / अनुमति

Forbidden

Key वैध है लेकिन इस endpoint के लिए आवश्यक predict:read scope नहीं है।

{
  "error": "Insufficient permissions. Required scope: predict:read",
  "code": "insufficientScope"
}
404क्लाइंट त्रुटि

नहीं मिला

निर्दिष्ट शहर नहीं मिल सका।

{
  "error": "City not found",
  "code": "cityNotFound"
}
429क्लाइंट त्रुटि

Too Many Requests

दैनिक quota पार हो गई (free tier पर 100 requests/दिन)। UTC आधी रात को रीसेट; Retry-After header देखें।

{
  "error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
  "code": "rateLimitExceeded",
  "retryAfter": 3600
}
500सर्वर त्रुटि

सर्वर त्रुटि

एक आंतरिक सर्वर त्रुटि हुई। कृपया बाद में पुनः प्रयास करें।

{
  "error": "Internal server error"
}
502सर्वर त्रुटि

Bad Gateway

Upstream geocoding provider विफल रहा। थोड़ी देरी के साथ पुनः प्रयास करें; geocoding छोड़ने के लिए lat/lon भेजने पर विचार करें।

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

सर्वोत्तम अभ्यास

प्रतिक्रियाएं कैश करें

भविष्यवाणियाँ 30 मिनट के लिए कैश की जाती हैं। अधिक बार पोलिंग से बचें।

तारीख सीमा

भविष्यवाणियाँ आज से 5 दिन आगे तक उपलब्ध हैं। आगे की तारीखें कम सटीक परिणाम देती हैं।

निर्देशांक पसंद करें

lat/lon का उपयोग अधिक सटीक है और क्षेत्रों में साझा शहर नामों के साथ अस्पष्टता से बचाता है।

त्रुटियों को शालीनता से संभालें

हमेशा HTTP स्थिति कोड की जांच करें और 400/404/500 प्रतिक्रियाओं को उचित रूप से संभालें।

Rate limits का सम्मान करें

हर response पर X-RateLimit-Remaining पढ़ें। 429 पर, पुनः प्रयास करने से पहले Retry-After window (UTC आधी रात रीसेट) तक प्रतीक्षा करें।

Keys को server-side रखें

किसी public client bundle, mobile app, या repo में API key को कभी embed न करें। अपने backend के माध्यम से proxy करें और keys को env vars या किसी secret manager में संग्रहीत करें।

उपयोग और लाइसेंस

कब निःशुल्क टियर पर्याप्त है — और कब आपको सशुल्क प्लान चाहिए।

निःशुल्क टियर

व्यक्तिगत, शौक, स्मार्ट होम और परीक्षण उपयोग के लिए निःशुल्क।

  • •व्यक्तिगत प्रोजेक्ट और प्रोटोटाइप
  • •शौक और सीखना
  • •व्यक्तिगत उपयोग के लिए स्मार्ट होम डैशबोर्ड (जैसे Home Assistant)
  • •परीक्षण और मूल्यांकन

प्रति API कुंजी प्रतिदिन 100 अनुरोध।

Plus प्लान

व्यक्तिगत उपयोग के लिए अधिक सीमाएँ और विज्ञापन-मुक्त साइट। केवल व्यक्तिगत उपयोग — व्यावसायिक प्रोजेक्ट के लिए Pro आवश्यक है।

प्रति API कुंजी 200 अनुरोध/दिन, 2 API कुंजियाँ।

व्यावसायिक उपयोग

व्यावसायिक उपयोग के लिए सशुल्क प्लान चाहिए — Pro या Business।

सशुल्क टियर में अधिक दैनिक अनुरोध सीमाएँ और अधिक API कुंजियाँ होती हैं।

मूल्य देखें

Home Assistant और अन्य स्मार्ट होम एकीकरण व्यक्तिगत, गैर-व्यावसायिक उपयोग के लिए निःशुल्क टियर पर अनुमत रहते हैं।

अपनी API कुंजी गुप्त रखें। इसे सर्वर-साइड उपयोग करें और कभी भी सार्वजनिक क्लाइंट-साइड कोड में एम्बेड न करें या रिपॉज़िटरी में कमिट न करें।

क्या आप कुछ व्यावसायिक बना रहे हैं, या ऐसी सीमा से टकरा रहे हैं जिसे हल नहीं कर पा रहे? सहायता से संपर्क करें