新加坡 PM2.5 实时查询 API 接入：五区域浓度分级一站获取-育师

新加坡 PM2.5 实时查询 API 接入：五区域浓度分级一站获取

摘要：本文以 GooFuture 新加坡 PM2.5 实时查询 API 为例，演示如何把新加坡国家空气质量监测数据快速接入自己的产品。从问题背景、接口调用、常见踩坑到适用场景，整理成一份可复现的接入笔记，方便日后检索。

一、问题背景：出海产品为什么需要新加坡空气质量数据

做出海健康类、智能家居类产品的团队，经常会遇到一个具体需求：给新加坡用户推送「今天空气怎么样、出门要不要戴口罩」的提醒。

难点不在于「想不想做」，而在于「数据怎么来」。新加坡国家空气质量数据按五个区域（北部、南部、东部、西部、中部）发布，每小时更新一次。原始数据给的是 PM2.5 浓度数值（微克 / 立方米），但要把它变成产品里能用的能力，至少还要解决四件事：

格式分散：监测数据以区域为单位零散发布，时间戳和字段结构并不完全统一，长期维护成本高。
只有浓度、没有等级：浓度到多少算良好、到多少算不健康，需要自己写分级规则。规则看着简单，做不准就容易误判。
拿不到历史趋势：官方只给当前时点快照，想做周报或长期环境分析，得自己长期存、自己攒。
超标了没人通知：空气质量突变时，系统本该自动触发设备动作或出行建议，但原始数据没有推送机制，只能靠轮询或人工盯。

对产品团队来说，这几件事都不是业务价值本身，而是「为了拿到业务数据必须先填的坑」。

二、解决方案：用一组 REST API 拿到标准化结果

把数据接入这件事，从「自己搭一套数据管道」换成「调用一组现成接口」，核心是三件事：

数据标准化：拿到的就是干净的结构化结果，五个区域的浓度、等级、坐标一次性给全。
结果带分级：PM2.5 浓度直接映射成等级，不用自己写判断逻辑。通行分级为：0–55 良好、56–150 中等、151–250 不健康、251 及以上非常不健康。
变化能预警：浓度越过你设的阈值，主动推送通知，而不是你不停地轮询「现在超标了没」。

GooFuture 新加坡 PM2.5 实时查询 API 提供的正是「采集 → 校验 → 分级 → 聚合 → 存储 → 交付」整条链路后的标准化结果，对外是一组 REST API（系统里点一下就能调到的接口），返回结构化 JSON。

2.1 全区域查询：一次拿到五个区现状

一个请求返回五个区的实时 PM2.5 浓度、空气质量等级和更新时间。

curl"https://api.goofuture.com/v1/sg/pm25"\-H"Authorization: Bearer {api_key}"

返回的 JSON 里，每个区域都带浓度、等级和经纬度坐标，可以直接标到地图组件上。

2.2 单区域查询：只取你服务的那一片

用户只在新加坡西部活动，就没必要每次拉全岛数据。按区域名（west / east / north / south / central）查询。

curl"https://api.goofuture.com/v1/sg/pm25/west"\-H"Authorization: Bearer {api_key}"

2.3 历史趋势：24 小时、7 天、30 天

健康类应用做周报、做长期环境分析，需要过去一段时间的变化曲线。历史趋势接口按小时粒度返回指定区域过去 24 小时、7 天或 30 天的浓度变化。

curl"https://api.goofuture.com/v1/sg/pm25/history?region=west&period=24h"\-H"Authorization: Bearer {api_key}"

2.4 超标预警：浓度越线自动推 Webhook

这一条对智能家居和出行场景最实用。订阅指定区域的 PM2.5 阈值，一旦越线，通过 Webhook（你系统里一个接收通知的地址）主动把预警推过来，空气净化器、出行建议就能自动跟着动。

curl-XPOST"https://api.goofuture.com/v1/sg/pm25/alerts"\-H"Authorization: Bearer {api_key}"\-H"Content-Type: application/json"\-d'{"region": "west", "threshold": 55, "webhook_url": "https://your-app.com/webhook"}'

三、踩坑与排查：接入前先确认两件事

预估真实调用量：套餐按「月请求量」分级，从基础版的一万次 / 月到企业版定制不等。健康类 App 按打开次数算、智能家居按设备数算，差出一个数量级，选错档位要么不够用、要么多花钱。
数据覆盖范围：目前接口只覆盖新加坡全岛五个监测区域。如果做的是马来西亚、印尼等其他东南亚市场，这套接口暂时覆盖不到，需要另找方案或等后续扩展。