Tài liệu API
Tích hợp dự đoán chất lượng hoàng hôn vào ứng dụng của bạn
Nhận khóa API để theo dõi lượt dùng của bạnBắt đầu nhanh
Nhận dự đoán hoàng hôn chỉ trong vài giây
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Thay $SUNSET_API_KEY bằng khóa từ trang quản lý của bạn. Các lệnh gọi không xác thực vẫn chạy được để thử nhanh, nhưng giới hạn chặt hơn và không có header giới hạn tốc độ.
Phản hồi mẫu
{
"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ác thực
Các yêu cầu từ bên ngoài được xác thực qua header x-api-key. Hãy tạo khóa từ trang quản lý của bạn — khóa gốc chỉ hiển thị đúng một lần.
Header
x-api-key: sp_live_YOUR_API_KEY_HEREGửi khóa API của bạn trong header yêu cầu x-api-key ở mọi lệnh gọi.
Phạm vi quyền
| Phạm vi | Mô tả |
|---|---|
| predict:read | Đọc dự đoán hoàng hôn (bắt buộc cho /api/predict) |
| usage:read | Đọc thống kê sử dụng của chính khóa này (bắt buộc cho /api/usage) |
Giới hạn
Gói Free — 100 yêu cầu mỗi ngày cho mỗi khóa, đặt lại vào nửa đêm UTC.
Header phản hồi về giới hạn tốc độ
Mọi phản hồi xác thực thành công đều kèm các header này để bạn theo dõi hạn mức theo thời gian thực:
| X-RateLimit-Limit | Số yêu cầu tối đa được phép trong khoảng thời gian hiện tại |
| X-RateLimit-Remaining | Số yêu cầu còn lại trong hôm nay |
| X-RateLimit-Reset | Mốc thời gian ISO 8601 khi hạn mức được đặt lại |
| Retry-After | Số giây cần chờ trước khi thử lại (chỉ với lỗi 429) |
Ví dụ yêu cầu đã xác thực
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Tham chiếu điểm cuối
Sân thử API
Thử API ngay trên trình duyệt của bạn. Dán khóa API để thực hiện lệnh gọi đã xác thực (tính vào hạn mức hằng ngày của bạn); để trống để thực hiện lệnh gọi demo không xác thực.
Bắt đầu bằng sp_live_ và dài 40 ký tự
Chỉ được lưu trong thẻ trình duyệt này (sessionStorage). Sẽ bị xóa khi bạn đóng thẻ.
Từ hôm nay đến 5 ngày tới. Để trống để lấy hôm nay.
URL yêu cầu
Ví dụ mã
Các ví dụ dùng ngay bằng những ngôn ngữ phổ biến
# 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"Các đoạn mã sẽ cập nhật trực tiếp khi bạn thay đổi tham số trong sân thử ở trên.
Phản hồi lỗi
Các phản hồi lỗi thường gặp và ý nghĩa của chúng
Yêu cầu không hợp lệ
Thiếu tham số hoặc tham số không hợp lệ. Hãy cung cấp city hoặc lat/lon.
{
"error": "Either lat/lon or city must be provided"
}Chưa được xác thực
Khóa API bị thiếu, sai định dạng hoặc đã bị thu hồi. Hãy gửi khóa hợp lệ trong header x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Bị từ chối
Khóa hợp lệ nhưng thiếu quyền predict:read mà điểm cuối này yêu cầu.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Không tìm thấy
Không tìm thấy thành phố đã chỉ định.
{
"error": "City not found",
"code": "cityNotFound"
}Quá nhiều yêu cầu
Đã vượt hạn mức hằng ngày (100 yêu cầu/ngày ở gói Free). Đặt lại vào nửa đêm UTC; hãy kiểm tra header Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Lỗi máy chủ
Đã xảy ra lỗi máy chủ nội bộ. Vui lòng thử lại sau.
{
"error": "Internal server error"
}Cổng không hợp lệ
Nhà cung cấp định vị địa lý phía trên gặp lỗi. Hãy thử lại sau một chút; cân nhắc gửi lat/lon để bỏ qua bước định vị.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Thực hành tốt nhất
Lưu đệm phản hồi
Dự đoán được lưu đệm phía máy chủ trong 20 phút cho mỗi (lat, lon, lang, date). Hãy tránh truy vấn dồn dập hơn mức đó.
Phạm vi ngày
Dự đoán có sẵn từ hôm qua đến 5 ngày tới. Các ngày xa hơn cho kết quả kém chính xác hơn.
Ưu tiên dùng tọa độ
Dùng lat/lon chính xác hơn, tránh nhầm lẫn với các tên thành phố trùng nhau ở nhiều vùng, và bỏ qua bước định vị.
Xử lý lỗi một cách khéo léo
Hãy kiểm tra mã trạng thái HTTP và trường code trong phản hồi. Hiển thị lỗi 401/403 cho người dùng và giảm tần suất gọi khi gặp 429 dựa theo Retry-After.
Tuân thủ giới hạn tốc độ
Hãy đọc X-RateLimit-Remaining ở mọi phản hồi. Khi gặp 429, hãy chờ hết khoảng Retry-After (đặt lại vào nửa đêm UTC) rồi mới thử lại.
Giữ khóa ở phía máy chủ
Không bao giờ nhúng khóa API vào gói mã công khai phía máy khách, ứng dụng di động hay kho mã. Hãy chuyển tiếp qua backend của bạn và lưu khóa trong biến môi trường hoặc trình quản lý bí mật.
Sử dụng và cấp phép
Khi nào gói Free là đủ — và khi nào bạn cần gói trả phí.
Gói Free
Miễn phí cho mục đích cá nhân, sở thích, nhà thông minh và thử nghiệm.
- •Dự án cá nhân và bản mẫu
- •Sở thích và học tập
- •Bảng điều khiển nhà thông minh (VD: Home Assistant) cho mục đích cá nhân
- •Thử nghiệm và đánh giá
100 yêu cầu/ngày cho mỗi khóa API.
Gói Plus
Giới hạn cá nhân cao hơn dành cho người ủng hộ, cùng trang web không quảng cáo. Chỉ dành cho mục đích cá nhân — dự án thương mại cần gói Pro.
200 yêu cầu/ngày cho mỗi khóa API, 2 khóa API.
Sử dụng thương mại
Sử dụng thương mại cần gói trả phí — Pro hoặc Business.
Các gói trả phí có giới hạn yêu cầu hằng ngày cao hơn và cho phép nhiều khóa API hơn.
Xem bảng giáHome Assistant và các tích hợp nhà thông minh khác vẫn được phép dùng ở gói Free cho mục đích cá nhân, phi thương mại.
Hãy giữ bí mật khóa API của bạn. Chỉ dùng ở phía máy chủ, không nhúng vào mã công khai phía máy khách và không commit lên kho mã.
Bạn đang xây dựng một sản phẩm thương mại hoặc gặp giới hạn mà không tự giải quyết được? Liên hệ hỗ trợ