API

先查城市，再取完整时间数据。

SunriseTime API 先帮你发现城市 slug，再按城市返回太阳、月相和礼拜时间数据。当前目录覆盖 500 座已索引城市。

当前接入方式

公开 beta
暂不要求 API key
适合原型、脚本和轻量查询
当前目标为每个 IP 每天 100 次请求

产品基础

统一走 /api/v1/
每个 JSON 响应都带 meta 块
第三方浏览器侧 CORS 目前仍有限制
API 返回会附带 X-Robots-Tag: noindex

缓存策略

/api/v1/times：15 分钟
/api/v1/cities：60 分钟
/api/v1/openapi.json：60 分钟

快速开始

推荐先查城市 slug，再按 slug 请求时间数据。

1. 查询城市 slug

curl "https://sunrisetime.co/api/v1/cities?query=shanghai&limit=3"

2. 请求时间数据

curl "https://sunrisetime.co/api/v1/times?city=shanghai&date=2026-03-29"

接口列表

这三条接口已经足够覆盖大部分外部接入场景。

GET /api/v1/cities 按城市名、slug、国家或地区查找支持的城市，并返回稳定 slug。 GET /api/v1/times 按城市和日期返回日出、日落、黄金时刻、月相和礼拜时间。 GET /api/v1/openapi.json 读取机器可读的 OpenAPI 描述，方便生成客户端或做内部工具。

参数说明

保持流程简单最稳妥：先拿 slug，再一次请求一座城市。

`/api/v1/cities`

参数	必填	说明
`query`	否	城市、slug、国家或行政区。留空时返回热门城市。
`limit`	否	默认 10，最大 25。

`/api/v1/times`

参数	必填	说明
`city`	是	稳定城市 slug，例如 shanghai、tokyo、london。
`date`	否	可选，本地日期格式为 YYYY-MM-DD。

响应结构

JSON 按使用场景分组，方便直接接入，而不是只暴露底层计算字段。

JSON

meta：版本、接口、文档地址、缓存 TTL 与查询回显
city：slug、名称、坐标、时区与人口元数据
links：与该城市相关的网站和 API 链接
sun、goldenHour、moon、prayerTimes 四个核心块

Sample response

{
  "meta": {
    "version": "v1",
    "endpoint": "/api/v1/times",
    "cacheTtlSeconds": 900
  },
  "city": {
    "slug": "shanghai",
    "name": "Shanghai",
    "timezone": "Asia/Shanghai"
  },
  "sun": {
    "sunrise": "5:43 AM",
    "sunset": "6:08 PM"
  },
  "moon": {
    "phase": "Waxing Crescent",
    "illumination": 12
  },
  "prayerTimes": {
    "fajr": "4:46 AM",
    "maghrib": "6:09 PM"
  }
}

集成示例

当前更适合命令行、脚本或服务端调用。第三方浏览器直连建议等更完整的 CORS 策略上线后再用。

cURL

curl "https://sunrisetime.co/api/v1/times?city=shanghai&date=2026-03-29"

JavaScript

const cityLookup = await fetch("https://sunrisetime.co/api/v1/cities?query=shanghai&limit=1");
const cityResult = await cityLookup.json();
const citySlug = cityResult.cities[0]?.slug;

const timingResponse = await fetch(`https://sunrisetime.co/api/v1/times?city=${citySlug}&date=2026-03-29`
);
const timingData = await timingResponse.json();

console.log(timingData.sun.sunrise, timingData.prayerTimes.maghrib);

错误模型

错误返回结构化 JSON，便于在脚本、前端或服务端里直接判断。

错误码	状态码	含义
`missing_city`	400	/api/v1/times 没有传 city 参数。
`invalid_date`	400	date 不是合法的 YYYY-MM-DD。
`unknown_city`	404	传入的城市 slug 不在当前索引中。
`invalid_limit`	400	/api/v1/cities 的 limit 参数不合法。

接下来怎么用

如果你想继续核对方法、检查城市 slug，或者申请更高额度，可以看下面三个入口。

方法说明 查看太阳、月相和礼拜时间的计算假设。 城市索引 如果你想人工检查 slug，可以直接浏览城市索引页。 联系支持 如果你需要更高配额或专门接入方案，可邮件联系 hello@sunrisetime.co。