快速入門
幾秒鐘就能取得日落預測
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"請將 $SUNSET_API_KEY 替換為您主控台中的金鑰。未驗證的呼叫可用於快速示範，但限制較嚴格，且不會回傳速率限制標頭。
回應範例
{
"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每次呼叫時，請在 x-api-key 請求標頭中傳送您的 API 金鑰。
權限範圍
| 權限範圍 | 說明 |
|---|---|
| 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。貼上您的 API 金鑰即可發出已驗證的呼叫（會計入每日配額）；留空則會發出未驗證的示範呼叫。
今天至 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
金鑰有效，但缺少此端點所需的 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"
}最佳做法
快取回應
預測結果會在伺服器端依 (lat, lon, lang, date) 快取 20 分鐘。請避免更頻繁地輪詢。
日期範圍
可查詢昨天至 5 天後的預測。更遠的日期準確度較低。
優先使用座標
使用 lat/lon 更精確，可避免不同地區同名城市造成的混淆，並略過地理編碼。
妥善處理錯誤
請檢查 HTTP 狀態碼與回應中的 code 欄位。將 401/403 告知使用者，遇到 429 時依 Retry-After 延後重試。
遵守速率限制
每次回應都請讀取 X-RateLimit-Remaining。遇到 429 時，請等候 Retry-After 時段（UTC 午夜重設）結束後再重試。
金鑰請保留在伺服器端
切勿將 API 金鑰嵌入公開的用戶端程式包、行動 App 或程式碼儲存庫。請透過您的後端代理請求，並將金鑰存放在環境變數或密鑰管理服務中。
使用與授權
什麼情況下免費方案就夠用，什麼情況下需要付費方案。
免費方案
可免費用於個人、興趣、智慧家庭與測試用途。
- •個人專案與原型
- •興趣與學習
- •個人使用的智慧家庭儀表板（例如 Home Assistant）
- •測試與評估
每個 API 金鑰每天 100 次請求。
Plus 方案
為支持者提供更高的個人使用上限，並享有無廣告網站。僅限個人使用，商業專案需使用 Pro。
每個 API 金鑰每天 200 次請求，2 組 API 金鑰。
Home Assistant 及其他智慧家庭整合，在個人、非商業用途下仍可使用免費方案。
請妥善保管您的 API 金鑰。請在伺服器端使用，切勿嵌入公開的用戶端程式碼或提交至程式碼儲存庫。
正在打造商業產品，或遇到無法解決的上限問題？ 聯絡客服