日出日落

按全球城市和指定日期查询当地日出、日落、日光时长及其日变化、天文/航海/民用曙暮光、太阳正午和日地距离。历史日期与近期日期使用同一套返回字段，原有入参与返回结构保持兼容。极昼、极夜等情况下，当日客观不存在的天文事件字段可能为空字符串。

核心功能：

支持按全球城市名称查询日出日落信息，便于为国内外目的地提供统一的天文时间展示

通过城市和指定日期查询，支持历史日期，便于回看某一天的日照情况或逐日整理季节变化

天文时刻按查询城市的当地时间返回，并考虑当地时区与夏令时，便于展示目的地时间

同时返回日出和日落时刻，可用于旅行行程、户外活动与日出日落拍摄的时间参考

提供当天白昼总时长，以时、分、秒表示，方便在日历和城市看板中展示日照长度

返回白昼时长相较前一天的增减值，便于直观看到白天正在变长还是变短

提供民用曙暮光的开始和结束时刻，便于在生活服务页面补充晨昏时段信息

提供航海曙暮光的开始和结束时刻，可与民用曙暮光对照展示不同的晨昏阶段

提供天文曙暮光的开始和结束时刻，可为观星或天文摄影规划提供时间参考

返回太阳正午时刻，便于展示当地太阳运行的日内节点，无需将正午固定为钟表上的十二点

返回正午时刻的日地距离，单位为百万公里，适合天文科普卡片和季节变化展示

可与天气预报、空气质量或农历接口组合，在同一出行或日历页面中展示天气环境与天文时间
详情页：https://www.gugudata.com/api/details/sunrisesunset

当前接口契约

接口详情：https://www.gugudata.com/api/details/sunrisesunset

请求参数

参数	类型	必填	默认值	说明
appkey	string	否	无	付费后获取的 APPKEY AppKey 整体必填；在本操作已声明支持的鉴权位置任选一个提供，本位置无需重复填写。多处填写时须一致。
city	string	是	无	查询城市名，支持全球城市，如北京、南京、伦敦等
date	string	是	无	查询日期，格式为 yyyyMMdd，如 20260810

正常响应字段

字段	类型	说明
DataStatus.StatusCode	integer	接口返回状态码
DataStatus.StatusDescription	string	接口返回状态说明
DataStatus.ResponseDateTime	string	接口数据返回时间
DataStatus.DataTotalCount	integer	此条件下的总数据量，一般用于分页计算
Data.City	string	返回数据的城市名称
Data.SunriseTime	string	日出时间，格式为: hh:mm
Data.SunsetTime	string	日落时间，格式为: hh:mm
Data.DaylightHours	string	日光时间，格式为: hh:mm:ss
Data.DaylightHoursDiff	string	日光时间差，格式为: (+/-)hh:mm，+ 为较于前日增加，- 为较于前日减少
Data.AstroTwilightStart	string	天文曙暮光开始时间，格式为: hh:mm
Data.AstroTwilightEnd	string	天文曙暮光结束时间，格式为: hh:mm
Data.NauticalTwilightStart	string	航海曙暮光开始时间，格式为: hh:mm
Data.NauticalTwilightEnd	string	航海曙暮光结束时间，格式为: hh:mm
Data.CivilTwilightStart	string	民用曙暮光开始时间，格式为: hh:mm
Data.CivilTwilightEnd	string	民用曙暮光结束时间，格式为: hh:mm
Data.SolarNoonTime	string	正午时刻，格式为: hh:mm
Data.SolarNoonDistance	string	正午时刻太阳距离，单位为：百万公里

业务状态说明

业务状态码	业务状态码解释	备注
100	成功	HTTP 200
501	参数错误	HTTP 400
502	请求频率受限	HTTP 429
503	订单到期	HTTP 403
504	APPKEY 错误	HTTP 401
505	权限或额度不可用	HTTP 403
900	服务内部错误	HTTP 500
901	数据暂不可用或请求超时	HTTP 503

常见问题

城市和日期怎么填写？

city 填城市名，date 填 yyyyMMdd 格式的查询日期，例如 city=南京、date=20261110。查询不同城市时，每次传入一个城市名和一个日期。

返回时间是哪个时区？

日出、日落、曙暮光及正午时刻按查询城市的当地时间返回，并考虑当地时区与夏令时。跨城市比较时，请保留各城市所属时区。

白昼时长和白昼变化量如何读取？

DaylightHours 是当天的日光时长，格式为 hh:mm:ss。DaylightHoursDiff 表示与前一天的差，正号代表变长，负号代表变短。

需要民用、航海或天文曙暮光时看哪些字段？

民用曙暮光读取 CivilTwilightStart 和 CivilTwilightEnd，航海曙暮光读取 NauticalTwilightStart 和 NauticalTwilightEnd，天文曙暮光读取 AstroTwilightStart 和 AstroTwilightEnd。

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

成功（业务码 100）。

Bodyapplication/json

示例

{
  "DataStatus": {
    "RequestParameter": "city=南京&date=20260808",
    "StatusCode": 100,
    "StatusDescription": "请求成功。",
    "ResponseDateTime": "2026-08-10 11:18:07.681",
    "DataTotalCount": 1
  },
  "Data": {
    "City": "南京",
    "SunriseTime": "05:24",
    "SunsetTime": "18:56",
    "DaylightHours": "13:31:44",
    "DaylightHoursDiff": "+00:00",
    "AstroTwilightStart": "03:53",
    "NauticalTwilightStart": "04:26",
    "CivilTwilightStart": "04:58",
    "AstroTwilightEnd": "20:26",
    "NauticalTwilightEnd": "19:53",
    "CivilTwilightEnd": "19:22",
    "SolarNoonTime": "12:10",
    "SolarNoonDistance": "151.681"
  }
}

🟠400参数错误（业务码 501）。

🟠401APPKEY 错误（业务码 504）。

🟠403订单到期（业务码 503）；权限或额度不可用（业务码 505）。

🟠404资源不存在。请求路径不存在。

🟠405请求方法不允许。当前路径不支持该 HTTP 方法。

🟠415请求内容类型不支持。上传或请求体的内容类型不符合接口要求。

🟠429请求频率受限（业务码 502）。

🔴500服务内部错误（业务码 900）。

🔴502上游依赖错误。上游依赖服务不可用或返回异常。

🔴503数据暂不可用或请求超时（业务码 901）。

当前接口契约#

请求参数#

正常响应字段#

业务状态说明#

常见问题#

城市和日期怎么填写？#

返回时间是哪个时区？#

白昼时长和白昼变化量如何读取？#

需要民用、航海或天文曙暮光时看哪些字段？#

请求参数

请求示例代码

返回响应

当前接口契约

请求参数

正常响应字段

业务状态说明

常见问题

城市和日期怎么填写？

返回时间是哪个时区？

白昼时长和白昼变化量如何读取？

需要民用、航海或天文曙暮光时看哪些字段？