7 天预报接口：数组第一天可能不是明天｜数据鱼API

排行程的页面需要“未来七天”的气温曲线，产品默认数组第一个元素就是明天。上线后发现，标签写成了明天，日期却是今天，用户以为预报错了。逐日数组从当天开始，这一点在字段里能看出来，只是容易被忽略。

示例接口来自数据鱼API的「全球天气查询」服务，本文关注其中的「7 天预报」分支（GET /v1/api/weather/forecast）。返回未来 7 天逐日预报。

逐日数组按日期排列，覆盖未来 7 天。做气温曲线时，横轴直接用 date，不要用下标；做“最高温/最低温”区间时，用 temp_max 和 temp_min，不要拿 current_brief.temperature 代替。实况和预报是两个口径，混在一张图里要标注清楚。

预报和单点查询怎么分工

GET /v1/api/weather/forecast 只返回三块：data.city、data.current_brief 和 data.daily。query 返回完整的 current、hourly 和 daily。做七天行程页，预报接口更轻；要逐小时曲线，用查询接口。

两者入参一致：city 或 lat 加 lng，至少给一种；lang 控制描述语言，默认 zh。

字段怎么读

data.city 是字符串城市名，data.lat 和 data.lng 是本次查询的坐标。data.current_brief.temperature、weather_desc、wind_speed、humidity 组成顶部实况条。

data.daily[].date 是日期，temp_max 和 temp_min 是当天的温度区间。data.daily[].sunrise 和 sunset 适合做行程提示，precipitation_prob 是降水概率。data.meta.data_age_sec 是数据距今秒数，用于判断是否需要刷新。

current_brief 只有四个字段，适合做顶部摘要，不适合做详情面板。需要气压、云量、阵风时，还是要调用查询接口的 current 对象。七天预报的数据量不大，但不要在每个页面初始化时都请求一次，按城市缓存、切换城市再刷新，能减少重复调用。

今天和明天怎么判断

不要按下标。用 date 与当前日期比较，第一天可能正是今天。做“今天/明天/后天”标签时，先按日期匹配，匹配不上再显示星期。示例里查询时间与首条日期是同一天，正好说明这一点。跨月、跨年时不要用字符串截取比较，转成日期对象再算。sunrise 和 sunset 是当地时刻，展示时带上城市名。

和 query 的缓存差异

预报接口没有 force 参数，缓存策略由服务端控制；查询接口可以用 force 跳过缓存。需要强制刷新时，预报接口只能重新请求并观察 meta.data_age_sec。把两个接口的缓存行为写进接入文档，避免前端以为传了某个参数就会实时回源。

城市不存在返回 404，参数缺失返回 400，这两类错误不要重试。只有超时和服务端错误才进入重试队列。重试时保持 city 或坐标不变，不要在一次重试里切换入参类型。

时区与城市

预报返回里没有时区字段。跨时区城市展示日出日落时，最好同时显示城市名，避免用户按本地时间理解。城市名有歧义时，用坐标查询更稳，data.lat 和 data.lng 会回显本次使用的坐标。

curl -s --get "$API_BASE/v1/api/weather/forecast" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "city=北京" \
  --data "lang=zh"

四个坑

第一，把 daily[0] 当明天。首条可能是今天，标签会错一天。

第二，在预报接口里找 hourly。它不返回逐小时数据，需要逐时曲线就换查询接口。

第三，用城市名查同名城市。跨国家重名时结果不确定，坐标更可靠。

第四，忽略 meta.data_age_sec。预报数据也可能来自缓存，展示“刚刚更新”前先看这个值。

七天预报适合做行程和趋势，不适合做分钟级实况。把日期口径和接口分工定清楚，页面上的“明天”才不会写错。如果页面同时展示实况和七天预报，可以用 current_brief 做顶部，再按需调用查询接口补逐小时，避免一次拉取两份完整数据。

本文只讨论数据鱼API「全球天气查询」接口的接入方式，具体行为以官方文档为准。