日出日落与月相 API

按经纬度计算日出、日落、正午、民用晨昏蒙影与白昼时长，以及月相、月面亮度和下次满月/新月（本地天文计算）

数据来源：本地计算（NOAA 太阳位置算法 + Meeus《天文算法》月相）

返回统一的 JSON 格式 { code, message, cached, stale, updatedAt, data }，支持跨域，免注册每天可免费调用 100 次，注册后每天 10000 次。

某地某日的日出日落、白昼时长与月相

GET /api/sun

请求参数

  • lat（必填）：纬度 -90~90，北纬为正，示例 31.23
  • lon（必填）：经度 -180~180，东经为正，示例 121.47
  • date：日期 YYYY-MM-DD（1900–2100），默认该时区的今天，示例 2026-06-21
  • tz：IANA 时区名，输出时间按该时区显示，示例 Asia/Shanghai

返回字段

  • date（string）：日期 YYYY-MM-DD（所选时区的日历日）
  • weekday（string）：星期几，如 星期日
  • lat（number）：纬度
  • lon（number）：经度
  • tz（string）：时区（IANA 名）
  • utcOffset（string）：当天该时区相对 UTC 的偏移，如 +08:00
  • status（string）：日照状态：normal（正常）、polar_day（极昼，全天不落）、polar_night（极夜，全天不升）
  • statusText（string）：日照状态的中文说明
  • sunrise（string|null）：日出时间 HH:mm（本地时间，太阳上缘升出地平线，已计大气折射）；极昼/极夜时为 null
  • sunset（string|null）：日落时间 HH:mm；极昼/极夜时为 null
  • solarNoon（string）：正午（太阳中天、高度最高）时间 HH:mm
  • civilDawn（string|null）：民用晨光始（太阳高度 -6°，天开始亮）HH:mm；高纬度夏季整夜不暗或极夜全天不到 -6° 时为 null
  • civilDusk（string|null）：民用昏影终（太阳高度 -6°，天基本黑）HH:mm；无此现象时为 null
  • dayLength（string）：白昼时长中文，如 14 小时 50 分
  • dayLengthMinutes（number）：白昼时长（分钟），极昼为 1440，极夜为 0
  • noonAltitude（number）：正午太阳高度角（度，未计折射），负数表示正午太阳仍在地平线下
  • iso（object）：上述时刻的完整 ISO 8601 时间（带时区偏移）
  • iso.sunrise（string|null）：日出
  • iso.sunset（string|null）：日落
  • iso.solarNoon（string）：正午
  • iso.civilDawn（string|null）：民用晨光始
  • iso.civilDusk（string|null）：民用昏影终
  • moon（object）：月相（按当天本地 12:00 计算；不传 date 时按当前时刻）
  • moon.phase（string）：月相名称：新月、蛾眉月、上弦月、盈凸月、满月、亏凸月、下弦月、残月（当天恰逢朔/上弦/望/下弦时刻时为新月/上弦月/满月/下弦月）
  • moon.phaseKey（string）：月相英文键：new / waxingCrescent / firstQuarter / waxingGibbous / full / waningGibbous / lastQuarter / waningCrescent
  • moon.illumination（number）：月面被照亮的比例（%），0 为新月、100 为满月
  • moon.waxing（boolean）：true 为渐盈（新月→满月），false 为渐亏（满月→新月）
  • moon.age（number）：月龄：距上一次新月（朔）的天数，保留 1 位小数
  • moon.lastNewMoon（object）：上一次新月（朔）时刻
  • moon.lastNewMoon.date（string）：本地日期 YYYY-MM-DD

月相、月面亮度、月龄与下次满月/新月

GET /api/moon

请求参数

  • date：日期 YYYY-MM-DD（1900–2100），按当天本地 12:00 计算；默认当前时刻，示例 2026-09-26
  • tz：IANA 时区名，决定"当天"的范围与输出时间，示例 Asia/Shanghai

返回字段

  • date（string）：日期 YYYY-MM-DD（所选时区）
  • tz（string）：时区（IANA 名）
  • phase（string）：月相名称：新月、蛾眉月、上弦月、盈凸月、满月、亏凸月、下弦月、残月（当天恰逢朔/上弦/望/下弦时刻时为新月/上弦月/满月/下弦月）
  • phaseKey（string）：月相英文键：new / waxingCrescent / firstQuarter / waxingGibbous / full / waningGibbous / lastQuarter / waningCrescent
  • illumination（number）：月面被照亮的比例（%），0 为新月、100 为满月
  • waxing（boolean）：true 为渐盈（新月→满月），false 为渐亏（满月→新月）
  • age（number）：月龄：距上一次新月（朔）的天数，保留 1 位小数
  • lastNewMoon（object）：上一次新月（朔）时刻
  • lastNewMoon.date（string）：本地日期 YYYY-MM-DD
  • lastNewMoon.time（string）：本地时刻 HH:mm
  • lastNewMoon.iso（string）：带时区偏移的 ISO 8601 时间
  • nextNewMoon（object）：下一次新月（朔）
  • nextNewMoon.date（string）：本地日期 YYYY-MM-DD
  • nextNewMoon.time（string）：本地时刻 HH:mm
  • nextNewMoon.iso（string）：带时区偏移的 ISO 8601 时间
  • nextNewMoon.days（number）：距今还有多少天（1 位小数）
  • nextFullMoon（object）：下一次满月（望）
  • nextFullMoon.date（string）：本地日期 YYYY-MM-DD
  • nextFullMoon.time（string）：本地时刻 HH:mm
  • nextFullMoon.iso（string）：带时区偏移的 ISO 8601 时间
  • nextFullMoon.days（number）：距今还有多少天（1 位小数）