📋 API 文檔
BurnSky 燒天預測系統提供 RESTful API，讓開發者可以輕鬆整合燒天預測功能到自己的應用中。
基本資訊
- Base URL:
https://burnsky-api.onrender.com
- API 版本: v1
- 回應格式: JSON
- 認證: 不需要
API 端點
GET 燒天預測
GET /api/prediction
獲取當前的燒天預測資訊，包括機率、指數和建議拍攝時間。
查詢參數
| 參數 |
類型 |
必需 |
說明 |
| location |
string |
否 |
地點代碼 (預設: HK) |
| days |
integer |
否 |
預測天數 (1-7, 預設: 3) |
範例請求
curl -X GET "https://burnsky-api.onrender.com/api/prediction?location=HK&days=3"
範例回應
{
"status": "success",
"timestamp": "2024-12-27T10:30:00Z",
"location": "香港",
"predictions": [
{
"date": "2024-12-27",
"sunrise": "07:03",
"sunset": "17:56",
"burnsky_probability": 75,
"burnsky_index": 8.2,
"weather_conditions": {
"cloud_cover": 45,
"humidity": 65,
"wind_speed": 12,
"temperature": 22
},
"recommendation": "高機率，建議 17:30 開始準備拍攝"
}
]
}
GET 天氣資料
GET /api/weather
獲取詳細的天氣資料，包括溫度、濕度、風速等。
範例回應
{
"status": "success",
"weather": {
"temperature": 22,
"humidity": 65,
"wind_speed": 12,
"wind_direction": "東北",
"cloud_cover": 45,
"visibility": 15,
"uv_index": 3
}
}
GET 最佳拍攝地點
GET /api/locations
獲取推薦的燒天拍攝地點清單。
範例回應
{
"status": "success",
"locations": [
{
"name": "西環泳棚",
"coordinates": [22.2808, 114.1277],
"rating": 9.2,
"description": "絕佳西面海景，無遮擋視野",
"best_time": "日落前30分鐘"
},
{
"name": "石澳",
"coordinates": [22.2132, 114.2513],
"rating": 8.8,
"description": "開闊海景，多角度拍攝選擇",
"best_time": "日落前45分鐘"
}
]
}
錯誤處理
API 使用標準 HTTP 狀態碼。所有錯誤回應都包含錯誤資訊：
{
"status": "error",
"error_code": "INVALID_PARAMETER",
"message": "查詢參數無效",
"details": "days 參數必須在 1-7 之間"
}
速率限制
為確保服務穩定，API 實施以下速率限制：
- 每分鐘最多 60 次請求
- 每小時最多 1000 次請求
- 超出限制將回傳 429 狀態碼
使用範例
JavaScript (Fetch API)
async function getBurnskyPrediction() {
try {
const response = await fetch('https://burnsky-api.onrender.com/api/prediction');
const data = await response.json();
console.log('燒天機率:', data.predictions[0].burnsky_probability);
} catch (error) {
console.error('API 錯誤:', error);
}
}
Python
import requests
def get_burnsky_prediction():
try:
response = requests.get('https://burnsky-api.onrender.com/api/prediction')
data = response.json()
return data['predictions'][0]['burnsky_probability']
except requests.RequestException as e:
print(f'API 錯誤: {e}')
return None
支援
如有 API 使用問題或建議，請聯絡我們：