דלג לתוכן

תיעוד API

שלב תחזיות איכות שקיעה באפליקציות שלך

קבל מפתח API למעקב אחר השימוש שלך
כתובת בסיסhttps://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
  }
}

אימות

בקשות חיצוניות מתאמתות באמצעות הכותרת x-api-key. צרו מפתח מלוח הבקרה שלכם — המפתח הגולמי מוצג בדיוק פעם אחת.

כותרת

x-api-key: sp_live_YOUR_API_KEY_HERE

שלחו את מפתח ה-API שלכם בכותרת הבקשה x-api-key בכל קריאה.

הרשאות

הרשאהתיאור
predict:readקריאת תחזיות שקיעה (נדרש עבור /api/predict)
usage:readקריאת נתוני השימוש של המפתח עצמו (נדרש עבור /api/usage)

מגבלות

תוכנית חינמית — 100 בקשות ביום לכל מפתח, איפוס בחצות לפי UTC.

כותרות תגובה של הגבלת קצב

כל תגובה מאומתת מוצלחת נושאת את הכותרות הבאות כדי שתוכלו לעקוב אחר המכסה בזמן אמת:

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 ישירות מהדפדפן

קבלו מפתח ←

מתחיל ב-sp_live_ ואורכו 40 תווים

מאוחסן רק בכרטיסיית דפדפן זו (sessionStorage). נמחק כשסוגרים את הכרטיסייה.

מהיום ועד 5 ימים קדימה. השאירו ריק להיום.

כתובת בקשה

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"

הדוגמאות מתעדכנות בזמן אמת בהתאם לפרמטרים שלמעלה.

תגובות שגיאה

תגובות שגיאה נפוצות ומשמעותן

400שגיאת לקוח

בקשה שגויה

פרמטרים חסרים או לא תקינים. ספק עיר או lat/lon.

{
  "error": "Either lat/lon or city must be provided"
}
401אימות / הרשאות

לא מורשה

מפתח API חסר, פגום או שבוטל. שלחו מפתח תקין בכותרת x-api-key.

{
  "error": "Invalid or revoked API key",
  "code": "unauthorized"
}
403אימות / הרשאות

אסור

המפתח תקין אך חסרה לו ההרשאה predict:read הנדרשת עבור endpoint זה.

{
  "error": "Insufficient permissions. Required scope: predict:read",
  "code": "insufficientScope"
}
404שגיאת לקוח

לא נמצא

העיר שצוינה לא נמצאה.

{
  "error": "City not found",
  "code": "cityNotFound"
}
429שגיאת לקוח

יותר מדי בקשות

חרגתם מהמכסה היומית (100 בקשות ביום בתוכנית החינמית). איפוס בחצות לפי UTC; בדקו את הכותרת Retry-After.

{
  "error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
  "code": "rateLimitExceeded",
  "retryAfter": 3600
}
500שגיאת שרת

שגיאת שרת

אירעה שגיאת שרת פנימית. אנא נסה שוב מאוחר יותר.

{
  "error": "Internal server error"
}
502שגיאת שרת

שער שגוי

ספק הגאוקודינג שבמעלה הזרם נכשל. נסו שוב לאחר השהיה קלה; שקלו לשלוח lat/lon כדי לדלג על הגאוקודינג.

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

שיטות עבודה מומלצות

אחסן תגובות

תחזיות נשמרות במטמון ל-30 דקות. הימנע מתשאול בתדירות גבוהה יותר.

טווח תאריכים

תחזיות זמינות מהיום ועד 5 ימים קדימה. תאריכים רחוקים יותר מחזירים תוצאות פחות מדויקות.

העדף קואורדינטות

שימוש ב-lat/lon מדויק יותר ומונע אי-בהירות עם שמות ערים משותפים לאזורים שונים.

טפל בשגיאות בחינניות

תמיד בדוק את קוד סטטוס HTTP וטפל בתגובות 400/404/500 בהתאם.

כבדו את מגבלות הקצב

קראו את X-RateLimit-Remaining בכל תגובה. בשגיאת 429, המתינו לחלון Retry-After (איפוס בחצות לפי UTC) לפני ניסיון חוזר.

שמרו את המפתחות בצד השרת

לעולם אל תטמיעו מפתח API בחבילת לקוח ציבורית, באפליקציה לנייד או במאגר קוד. נתבו דרך ה-backend שלכם ואחסנו מפתחות במשתני סביבה או במנהל סודות.

שימוש ורישוי

מתי התוכנית החינמית מספיקה — ומתי צריך תוכנית בתשלום.

תוכנית חינם

חינם לשימוש אישי, תחביב, בית חכם ובדיקות.

  • •פרויקטים אישיים ואבות טיפוס
  • •תחביב ולמידה
  • •לוחות בית חכם (למשל Home Assistant) לשימוש אישי
  • •בדיקות והערכה

100 בקשות ביום לכל מפתח API.

מסלול Plus

מגבלות אישיות גבוהות יותר ואתר ללא פרסומות. לשימוש אישי בלבד — פרויקטים מסחריים דורשים Pro.

200 בקשות ביום לכל מפתח API, 2 מפתחות API.

שימוש מסחרי

שימוש מסחרי דורש תוכנית בתשלום — Pro או Business.

תוכניות בתשלום כוללות מגבלות יומיות גבוהות יותר ומאפשרות יותר מפתחות API.

צפו בתמחור

Home Assistant ואינטגרציות בית חכם אחרות נשארות מותרות בתוכנית החינמית לשימוש אישי, לא מסחרי.

שמרו על מפתח ה-API בסוד. השתמשו בו בצד השרת ולעולם אל תטמיעו אותו בקוד צד-לקוח ציבורי או תעלו אותו למאגר.

בונים משהו מסחרי או נתקלתם במגבלה שאי-אפשר לעקוף? יצירת קשר עם התמיכה