مستندات API
پیش‌بینی کیفیت غروب را در برنامه‌های خود ادغام کنید
برای پیگیری مصرف خود یک کلید API بگیریدشروع سریع
در چند ثانیه یک پیش‌بینی غروب آفتاب بگیرید
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
}
}احراز هویت
درخواست‌های خارجی از طریق هدر x-api-key احراز هویت می‌شوند. از داشبورد خود یک کلید بسازید — کلید خام دقیقاً یک بار نمایش داده می‌شود.
هدر
x-api-key: sp_live_YOUR_API_KEY_HEREکلید API خود را در هر فراخوانی در هدر درخواست x-api-key ارسال کنید.
Scopeها
| Scope | توضیحات |
|---|---|
| predict:read | خواندن پیش‌بینی‌های غروب آفتاب (برای /api/predict الزامی است) |
| usage:read | خواندن آمار مصرف خود این کلید (برای /api/usage الزامی است) |
محدودیت‌ها
سطح رایگان — 100 درخواست در روز برای هر کلید، با بازنشانی در نیمه‌شب UTC.
هدرهای پاسخ rate-limit
هر پاسخ موفق با احراز هویت این هدرها را دارد تا بتوانید سهمیه را به‌صورت لحظه‌ای پیگیری کنید:
| X-RateLimit-Limit | حداکثر درخواست‌های مجاز در بازه فعلی |
| X-RateLimit-Remaining | درخواست‌های باقی‌مانده امروز |
| X-RateLimit-Reset | مهر زمانی ISO 8601 زمان بازنشانی سهمیه |
| Retry-After | تعداد ثانیه‌های انتظار پیش از تلاش دوباره (فقط در 429) |
نمونه درخواست با احراز هویت
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"مرجع نقطه‌های پایانی
محیط آزمایش API
API را مستقیماً از مرورگر خود آزمایش کنید. برای فراخوانی با احراز هویت، کلید API خود را وارد کنید (از سهمیه روزانه شما کم می‌شود)؛ برای فراخوانی نمایشی بدون احراز هویت، آن را خالی بگذارید.
با sp_live_ شروع می‌شود و 40 نویسه طول دارد
فقط در همین زبانه مرورگر (sessionStorage) ذخیره می‌شود و با بستن زبانه پاک می‌شود.
از امروز تا 5 روز آینده. برای امروز خالی بگذارید.
URL درخواست
نمونه کدها
نمونه‌های آماده استفاده به زبان‌های برنامه‌نویسی محبوب
# 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"با تغییر پارامترهای محیط آزمایش در بالا، قطعه‌کدها به‌صورت زنده به‌روز می‌شوند.
پاسخ‌های خطا
پاسخ‌های خطای رایج و معنای آن‌ها
Bad Request
پارامترها ارسال نشده‌اند یا نامعتبرند. یا city یا lat/lon را ارائه دهید.
{
"error": "Either lat/lon or city must be provided"
}Unauthorized
کلید API ارسال نشده، بدشکل یا باطل‌شده است. یک کلید معتبر در هدر x-api-key ارسال کنید.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Forbidden
کلید معتبر است اما scope predict:read لازم برای این نقطه پایانی را ندارد.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Not Found
شهر مشخص‌شده پیدا نشد.
{
"error": "City not found",
"code": "cityNotFound"
}Too Many Requests
سهمیه روزانه تمام شده است (100 درخواست در روز در سطح رایگان). بازنشانی در نیمه‌شب UTC انجام می‌شود؛ هدر Retry-After را بررسی کنید.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Server Error
خطای داخلی سرور رخ داد. لطفاً بعداً دوباره تلاش کنید.
{
"error": "Internal server error"
}Bad Gateway
سرویس‌دهنده ژئوکدینگ بالادستی با خطا مواجه شد. با کمی تأخیر دوباره تلاش کنید؛ برای رد شدن از ژئوکدینگ، ارسال lat/lon را در نظر بگیرید.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}بهترین شیوه‌ها
پاسخ‌ها را کش کنید
پیش‌بینی‌ها در سمت سرور به مدت 20 دقیقه برای هر (lat, lon, lang, date) کش می‌شوند. از درخواست‌های مکرر با فاصله کمتر خودداری کنید.
بازه تاریخ
پیش‌بینی‌ها از دیروز تا 5 روز آینده در دسترس هستند. تاریخ‌های دورتر نتایج کم‌دقت‌تری برمی‌گردانند.
مختصات را ترجیح دهید
استفاده از lat/lon دقیق‌تر است، از ابهام نام شهرهای مشترک بین مناطق مختلف جلوگیری می‌کند و ژئوکدینگ را حذف می‌کند.
خطاها را به‌درستی مدیریت کنید
کد وضعیت HTTP و فیلد code در پاسخ را بررسی کنید. خطاهای 401/403 را به کاربر نشان دهید و در 429 با استفاده از Retry-After درخواست‌ها را به تعویق بیندازید.
محدودیت نرخ را رعایت کنید
در هر پاسخ X-RateLimit-Remaining را بخوانید. در 429، پیش از تلاش دوباره منتظر پایان بازه Retry-After (بازنشانی در نیمه‌شب UTC) بمانید.
کلیدها را در سمت سرور نگه دارید
هرگز کلید API را در بسته کد عمومی سمت کلاینت، اپلیکیشن موبایل یا مخزن کد قرار ندهید. درخواست‌ها را از طریق بک‌اند خود عبور دهید و کلیدها را در متغیرهای محیطی یا یک ابزار مدیریت اسرار نگه دارید.
استفاده و مجوز
چه زمانی سطح رایگان کافی است — و چه زمانی به طرح پولی نیاز دارید.
سطح رایگان
رایگان برای استفاده شخصی، سرگرمی، خانه هوشمند و آزمایش.
- •پروژه‌ها و نمونه‌های اولیه شخصی
- •سرگرمی و یادگیری
- •داشبوردهای خانه هوشمند (مثلاً Home Assistant) برای استفاده شخصی
- •آزمایش و ارزیابی
100 درخواست در روز برای هر کلید API.
سطح Plus
سقف‌های شخصی بالاتر برای حامیان، به‌علاوه سایت بدون تبلیغات. فقط برای استفاده شخصی — پروژه‌های تجاری به Pro نیاز دارند.
200 درخواست در روز برای هر کلید API، 2 کلید API.
استفاده تجاری
استفاده تجاری به طرح پولی نیاز دارد — Pro یا Business.
سطح‌های پولی سقف درخواست روزانه بالاتری دارند و کلیدهای API بیشتری مجاز می‌کنند.
مشاهده قیمت‌هاHome Assistant و سایر یکپارچه‌سازی‌های خانه هوشمند برای استفاده شخصی و غیرتجاری همچنان در سطح رایگان مجاز هستند.
کلید API خود را محرمانه نگه دارید. از آن در سمت سرور استفاده کنید و هرگز آن را در کد عمومی سمت کلاینت قرار ندهید یا در مخزن کد ثبت نکنید.
در حال ساخت محصولی تجاری هستید یا به محدودیتی برخورده‌اید که نمی‌توانید حلش کنید؟ تماس با پشتیبانی