拾光潮汐 API 文档

概述

拾光潮汐 JSON API 提供 24 个滨海城市的潮汐数据、赶海评级、日出日落时刻等结构化数据，供第三方应用（小程序、App 等）调用。

API 为静态 JSON 端点，由 Hugo 构建时生成，托管于边缘 CDN，无速率限制。

端点

1. 城市索引 API

获取 24 个城市列表及各自本周摘要。

端点： GET /city-index.json

响应示例：

{
  "api_version": "1.0",
  "title": "拾光潮汐",
  "description": "捡拾潮汐间的时光——赶海·海钓·日出日落·城市情报",
  "base_url": "https://shiguangchaoxi.cn/",
  "generated_at": "2026-07-23T08:00:00+08:00",
  "total_cities": 24,
  "cities": [
    {
      "slug": "qingdao",
      "name": "青岛",
      "region": "华东",
      "week": "7/20-7/26",
      "weekly_api_url": "https://shiguangchaoxi.cn/qingdao/weekly/",
      "summary": "本周青岛大潮在周一、周二和周日，赶海最佳窗口在清晨退潮时段……"
    }
  ]
}

响应字段：

字段	类型	说明
`api_version`	string	API 版本号
`title`	string	站点标题
`description`	string	站点描述
`base_url`	string	站点根 URL
`generated_at`	string	生成时间（ISO 8601）
`total_cities`	integer	城市总数
`cities`	array	城市列表
`cities[].slug`	string	城市拼音标识（用于周报端点）
`cities[].name`	string	城市中文名
`cities[].region`	string	所属区域（华北/华东/华南/海南）
`cities[].week`	string	当前周起止日期
`cities[].weekly_api_url`	string	该城市周报 JSON 端点 URL
`cities[].summary`	string	本周潮汐概况文字描述

2. 城市周报 API

获取指定城市本周 7 天的完整潮汐、赶海评级、天气数据。

端点： GET /{slug}/weekly-guide-{date}/index.json

示例：GET /qingdao/weekly-guide-0720-0726/index.json

响应示例：

{
  "api_version": "1.0",
  "generated_at": "2026-07-23T08:00:00+08:00",
  "city": "qingdao",
  "city_name": "青岛",
  "week": "7/20-7/26",
  "page_url": "https://shiguangchaoxi.cn/qingdao/weekly-guide-0720-0726/",
  "days": [
    {
      "date": "7/20",
      "day_name": "周一",
      "tide_type": "大潮·活汛",
      "low_tide": "03:30 / 15:50",
      "low_height": "0.8m / 1.1m",
      "high_tide": "09:40 / 21:55",
      "high_height": "4.8m / 4.5m",
      "best_time": "00:30-03:30 / 12:50-15:50",
      "rating": "🔥",
      "note": "早潮赶海绝佳，红岛蛤蜊肥"
    }
  ],
  "spots": [
    "红岛蛤蜊滩",
    "栈桥礁石区",
    "石老人潮间带",
    "金沙滩赶海园",
    "唐岛湾湿地"
  ],
  "sunrise_sunset": [
    { "date": "7/20", "sunrise": "04:55", "sunset": "19:12" }
  ],
  "summary": "本周青岛大潮在周一、周二和周日……"
}

响应字段：

字段	类型	说明
`api_version`	string	API 版本号
`generated_at`	string	生成时间
`city`	string	城市拼音标识
`city_name`	string	城市中文名
`week`	string	本周起止日期（M/D-M/D）
`page_url`	string	对应 HTML 页面链接
`days`	array	7 天逐日数据
`days[].date`	string	日期（M/D）
`days[].day_name`	string	星期几
`days[].tide_type`	string	潮汐类型
`days[].low_tide`	string	低潮时刻
`days[].low_height`	string	低潮潮高
`days[].high_tide`	string	高潮时刻
`days[].high_height`	string	高潮潮高
`days[].best_time`	string	最佳赶海窗口
`days[].rating`	string	赶海评级（🔥/✅/⚠️/❌）
`days[].note`	string	当日备注
`days[].weather`	object	天气数据（可选）
`days[].weather.temp_max`	number	最高温（°C）
`days[].weather.temp_min`	number	最低温（°C）
`days[].weather.precip_prob`	integer	降水概率（%）
`days[].weather.wind_beaufort`	integer	风力（蒲福风级）
`days[].weather.weather_text`	string	天气描述
`spots`	array	推荐赶海点列表
`sunrise_sunset`	array	日出日落时刻
`summary`	string	本周潮汐概况

评级对照表

评级	含义	建议
🔥	爆赶级	大潮活汛，滩涂大面积露出，强烈推荐
✅	推荐级	中潮活汛，可赶海，收获尚可
⚠️	可玩级	小潮或天气不佳，勉强可去
❌	劝退级	小潮死汛或恶劣天气，不建议

使用说明

缓存策略

JSON 端点由 Hugo 构建时生成，建议客户端设置合理的缓存时间：

城市索引：Cache-Control: max-age=3600（1 小时），数据每日更新
城市周报：Cache-Control: max-age=7200（2 小时）

速率限制

API 为静态文件，托管于 CDN，无速率限制。但建议客户端合理设置缓存，避免对源站造成不必要压力。

版本策略

api_version 字段标注当前 API 版本
新增字段向后兼容，不破坏现有结构
重大变更将提前通知（通过 Newsletter 或首页公告）

常见问题

Q: 为什么某天的 weather 字段为空？ A: 天气数据由外部气象 API 拉取，仅在构建时已获取到的日期填充。若天气 API 未返回某日数据，则 weather 字段不会出现在该日。

Q: 数据更新频率？ A: 每周日/周一更新下周潮汐数据。天气数据每日更新。

Q: 支持 HTTPS 吗？ A: 是，所有端点均通过 HTTPS 提供。 （内容由AI生成，仅供参考）

概述#

端点#

1. 城市索引 API#

2. 城市周报 API#

评级对照表#

使用说明#

缓存策略#

速率限制#

版本策略#

常见问题#

概述

端点