API 文档

将日落质量预测集成到您的应用程序中

基础 URLhttps://sunset-predictor.com

快速开始

几秒钟内获取日落预测

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

Endpoint

API 密钥（可选）获取密钥 →

以 sp_live_ 开头，长度为 40 个字符

仅存储在当前浏览器标签页中（sessionStorage）。关闭标签页后即被清除。

城市

纬度

经度

日期

从今天起 5 天内。留空表示今天。

语言

单位

请求 URL

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"

示例会根据上方 playground 参数实时更新。

错误响应

常见错误响应及其含义

400客户端错误

请求错误

缺少或无效的参数。请提供城市或经纬度。

{
  "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 权限。

{
  "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天。更远的日期返回准确性较低的结果。

优先使用坐标

使用经纬度更精确，可避免跨地区的同名城市歧义。

优雅处理错误

始终检查 HTTP 状态码并适当处理 400/404/500 响应。

遵守速率限制

在每次响应中读取 X-RateLimit-Remaining。遇到 429 时，请等待 Retry-After 时间窗口（UTC 午夜重置）后再重试。

将密钥保存在服务端

切勿将 API 密钥嵌入公开的客户端打包文件、移动应用或代码仓库中。请通过你的后端进行代理，并将密钥存储在环境变量或密钥管理工具中。

使用与许可

何时免费版足够，何时需要付费套餐。

免费版

个人、爱好、智能家居和测试用途免费。

•个人项目与原型
•兴趣与学习
•个人使用的智能家居仪表盘（如 Home Assistant）
•测试与评估

每个 API 密钥每天 100 次请求。

Plus 套餐

更高的个人使用额度，并且没有广告。仅限个人使用——商业项目需要 Pro。

每个 API 密钥每天 200 次请求，2 个 API 密钥。

商业用途

商业使用需要付费套餐——专业版或商业版。

付费套餐有更高的每日请求上限，并允许更多 API 密钥。

查看价格

Home Assistant 及其他智能家居集成在个人非商业用途下，仍可在免费版使用。

请对 API 密钥保密。在服务器端使用，切勿嵌入公开的客户端代码或提交到代码仓库。

正在做商业项目，或者遇到了无法解决的限额问题？联系客服