城市名还是坐标：单点天气查询的两种入参｜数据鱼API

天气卡片上的时间写着“30 分钟前”，用户截图反馈数据不准。排查后发现，请求一直走缓存，force 从未打开；而缓存是否过期，接口在 meta 里写得很清楚。另一个问题是，同一个页面有时按城市名查，有时按定位坐标查，两种入参返回的城市信息并不完全一样。

这次拿数据鱼API的「全球天气查询」服务做示例，对应「单点天气查询」分支（GET /v1/api/weather/query）。按城市名或坐标查询单点天气，返回实况、未来 24 小时逐时与 7 天逐日。

两种入参，至少给一种

GET /v1/api/weather/query 支持两种方式：传 city 城市名，或者同时传 lat 与 lng。两者都不传返回 400；城市不存在返回 404；纬度范围 -90 到 90，经度范围 -180 到 180，非数字或越界都返回 400。

按城市名查询时，返回 data.city 对象，包含 name、country、latitude、longitude、timezone。按坐标查询时，响应里还会多一个 data.query，记录原始坐标。需要回显“你查询的位置”时，用这个字段。

选择哪种入参，取决于数据来源。用户在城市列表里选的城市，用 city 最直接；来自定位、地图点选或设备上报的坐标，用 lat 和 lng，避免反向解析城市名带来的歧义。同一个页面不要两种方式随机切换，否则缓存键和展示口径都会乱。

预报时效

单点查询一次返回三段时间：data.current 实况，data.hourly 未来 24 小时逐时，data.daily 未来 7 天逐日。只要实况时，把 brief 设为 true，会移除 hourly 和 daily，响应体大约降到十分之一。

brief 适合首页卡片，详情页要展示未来 24 小时和 7 天趋势，就保持默认。把它做成页面级配置，而不是全局开关，可以同时满足两类页面。

错误码怎么区分

400 是参数问题，404 是城市不存在，两者都不应该触发服务告警。参数问题检查 city 是否为空、lat 和 lng 是否成对、数值是否越界；404 则提示用户换一个城市。只有超时和 5xx 才值得进入重试队列。

缓存与新鲜度

force 为 true 时跳过缓存，强制回源，默认 false。不要每次请求都打开，否则缓存没有意义。判断数据是否新鲜，看 data.meta.freshness 和 data.meta.data_age_sec；示例里 freshness 是 stale，表示数据来自缓存且已经过了一段时间。

data_age_sec 是秒数，适合做自动刷新判断；data_age 是给人看的文本，适合直接展示。两者不要混用，前者可以参与逻辑，后者只用于界面。

展示细节

data.current.temperature 是温度，data.current.apparent_temp 是体感温度，data.current.is_day 用于切换昼夜图标，data.current.humidity 和 pressure 用于详情面板。lang 影响 weather_desc 的语言，默认 zh；需要双语时直接取 weather_desc_zh 和 weather_desc_en。

is_day 是 0 或 1，适合直接切换昼夜图标；不要用本地时间判断，跨时区时会出错。返回里的 timezone 是查询地时区，展示“当地时间”时用它，不要用浏览器时区。跨时区业务里，observed_at 和 fetched_at 的时区口径以接口文档为准，日志里同时记录时区标识更稳妥。

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

curl -s --get "$API_BASE/v1/api/weather/query" \
  -H "Authorization: Bearer $API_KEY" \
  --data "lat=39.9042" --data "lng=116.4074" \
  --data "force=true"

五个坑

第一，只传 lat 不传 lng。坐标必须成对出现，否则参数校验不通过。

第二，城市不存在返回 404，被当成服务故障。它是正常的“没这个城市”，换个城市名或坐标重试即可。

第三，brief=true 还去读 hourly 和 daily。精简模式下这两段不存在。

第四，忽略 meta.freshness，把缓存数据当实时数据展示。

第五，每次请求都开 force，缓存形同虚设，响应时间也会变长。

城市名适合用户输入，坐标适合定位场景。把两种入参的返回差异记清楚，天气页的展示口径就不会摇摆。缓存键按入参类型分开，城市名和坐标的缓存不要互相覆盖。缓存过期时间按页面刷新频率设置，不要照搬。

以上参数与返回字段以数据鱼API「全球天气查询」接口的公开文档为准，版本更新后请以最新说明为准。