เอกสาร 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 ทุกครั้งที่เรียก
สโคป
| สโคป | คำอธิบาย |
|---|---|
| predict:read | อ่านการคาดการณ์พระอาทิตย์ตก (จำเป็นสำหรับ /api/predict) |
| usage:read | อ่านสถิติการใช้งานของคีย์นี้เอง (จำเป็นสำหรับ /api/usage) |
ขีดจำกัด
แพ็กเกจ Free — 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 Playground
ทดสอบ 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"ตัวอย่างโค้ดจะอัปเดตทันทีเมื่อคุณเปลี่ยนพารามิเตอร์ใน Playground ด้านบน
การตอบกลับข้อผิดพลาด
การตอบกลับข้อผิดพลาดที่พบบ่อยและความหมาย
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 คำขอ/วันในแพ็กเกจ Free) รีเซ็ตเวลาเที่ยงคืน 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
ผู้ให้บริการ geocoding ต้นทางล้มเหลว โปรดลองใหม่หลังรอสักครู่ หรือส่ง lat/lon เพื่อข้ามขั้นตอน geocoding
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}แนวทางปฏิบัติที่ดี
แคชการตอบกลับ
การคาดการณ์จะถูกแคชฝั่งเซิร์ฟเวอร์เป็นเวลา 20 นาทีต่อ (lat, lon, lang, date) หลีกเลี่ยงการเรียกถี่กว่านี้
ช่วงวันที่
การคาดการณ์มีให้ตั้งแต่เมื่อวานถึงอีก 5 วันข้างหน้า วันที่ไกลกว่านั้นจะให้ผลลัพธ์ที่แม่นยำน้อยลง
ใช้พิกัดเป็นหลัก
การใช้ lat/lon แม่นยำกว่า หลีกเลี่ยงความกำกวมของชื่อเมืองที่ซ้ำกันในหลายภูมิภาค และข้ามขั้นตอน geocoding
จัดการข้อผิดพลาดอย่างเหมาะสม
ตรวจสอบรหัสสถานะ HTTP และฟิลด์ code ในการตอบกลับ แจ้ง 401/403 ให้ผู้ใช้ทราบ และชะลอการเรียกเมื่อได้ 429 โดยใช้ Retry-After
เคารพขีดจำกัดอัตรา
อ่านค่า X-RateLimit-Remaining ในทุกการตอบกลับ เมื่อได้ 429 ให้รอตามช่วง Retry-After (รีเซ็ตเวลาเที่ยงคืน UTC) ก่อนลองใหม่
เก็บคีย์ไว้ฝั่งเซิร์ฟเวอร์
อย่าฝังคีย์ API ไว้ในบันเดิลฝั่งไคลเอนต์สาธารณะ แอปมือถือ หรือรีโพสิทอรี ให้ส่งผ่านแบ็กเอนด์ของคุณ และเก็บคีย์ไว้ในตัวแปรสภาพแวดล้อมหรือระบบจัดการความลับ
การใช้งานและสิทธิ์การใช้
เมื่อใดที่แพ็กเกจ Free เพียงพอ — และเมื่อใดที่คุณต้องใช้แพ็กเกจแบบชำระเงิน
แพ็กเกจ Free
ใช้ฟรีสำหรับการใช้งานส่วนตัว งานอดิเรก สมาร์ทโฮม และการทดสอบ
- •โปรเจกต์ส่วนตัวและต้นแบบ
- •งานอดิเรกและการเรียนรู้
- •แดชบอร์ดสมาร์ทโฮม (เช่น Home Assistant) สำหรับใช้งานส่วนตัว
- •การทดสอบและการประเมิน
100 คำขอ/วันต่อคีย์ API
แพ็กเกจ Plus
ขีดจำกัดส่วนตัวที่สูงขึ้นสำหรับผู้สนับสนุน พร้อมเว็บไซต์ที่ไม่มีโฆษณา สำหรับการใช้งานส่วนตัวเท่านั้น — โปรเจกต์เชิงพาณิชย์ต้องใช้ Pro
200 คำขอ/วันต่อคีย์ API, คีย์ API 2 คีย์
การใช้งานเชิงพาณิชย์
การใช้งานเชิงพาณิชย์ต้องใช้แพ็กเกจแบบชำระเงิน — Pro หรือ Business
แพ็กเกจแบบชำระเงินมีขีดจำกัดคำขอรายวันที่สูงขึ้นและสร้างคีย์ API ได้มากขึ้น
ดูราคาHome Assistant และการเชื่อมต่อสมาร์ทโฮมอื่นๆ ยังใช้ได้ในแพ็กเกจ Free สำหรับการใช้งานส่วนตัวที่ไม่ใช่เชิงพาณิชย์
เก็บคีย์ API ของคุณเป็นความลับ ใช้งานฝั่งเซิร์ฟเวอร์ และอย่าฝังไว้ในโค้ดฝั่งไคลเอนต์สาธารณะหรือคอมมิตลงในรีโพสิทอรี
กำลังสร้างโปรเจกต์เชิงพาณิชย์ หรือเจอขีดจำกัดที่แก้ไม่ได้ใช่ไหม? ติดต่อฝ่ายสนับสนุน