单点查询 API

访问限制

本部分 API 属于增值服务，仅提供给企业套餐开发者，如需采购请联系彩云商务

TIP

目前支持美国地区的 CAP 气象预警信息，其他国家和地区的预警信息正在逐步增加中。

每次调用消耗接口调用额度一次。

• 错误信息 | 支持范围与数据粒度

请求

GET https://singer.caiyunhub.com/v3/cap_alert/location

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权
longitude	是	—	—	经度
latitude	是	—	—	纬度
language	否	zh-CN	BCP 47 语言标签	返回文本语言

请求示例

curl "https://singer.caiyunhub.com/v3/cap_alert/location?token={token}&longitude=-118.25&latitude=34.05&language=en-US"

响应示例

{
  "alerts": [
    {
      "id": "nws-alert-1",
      "region_code": "US",
      "source": 1,
      "msg_type": 1,
      "event_name": "Flash Flood Warning",
      "categories": [2],
      "urgency": 1,
      "severity": 2,
      "certainty": 2,
      "sent_time": 1750123200,
      "effective_time": 1750123200,
      "onset_time": 1750125000,
      "expires_time": 1750130400,
      "references": [],
      "areas": [
        {
          "area_desc": "Los Angeles",
          "geocodes": [
            {
              "value_name": "UGC",
              "value": "CAC037",
              "namespace": "NWS_UGC"
            }
          ],
          "polygons": [
            {
              "vertices": [
                { "latitude": 34.11, "longitude": -118.45 },
                { "latitude": 34.10, "longitude": -118.10 },
                { "latitude": 33.90, "longitude": -118.12 }
              ]
            }
          ],
          "circles": [
            {
              "center": { "latitude": 34.05, "longitude": -118.25 },
              "radius_km": 10
            }
          ]
        }
      ],
      "language_code": "en-US",
      "sender_name": "NWS Los Angeles/Oxnard CA",
      "headline": "Flash Flood Warning issued for Los Angeles",
      "description": "Flash flooding caused by excessive rainfall is expected.",
      "instruction": "Move to higher ground immediately."
    }
  ]
}

响应字段

CAPAlerts

JSONPath	类型	说明
$.alerts	array<object>	CAP 气象预警记录列表

CAPAlert

JSONPath	类型	说明
$.alerts[].id	string	预警唯一标识，不要直接解析 id 作为业务逻辑
$.alerts[].region_code	string	ISO 3166-1 Alpha-2 code
$.alerts[].source	number	预警来源机构，参考 CAPAlertSource
$.alerts[].msg_type	number	CAP msgType，参考 CAPAlertMsgType
$.alerts[].event_name	string	事件名称，优先使用请求语言对应文本中的事件名称
$.alerts[].categories	array<number>	CAP info.category，目前只返回 Met 类型，参考 CAPAlertCategory
$.alerts[].urgency	number	CAP info.urgency，参考 CAPAlertUrgency
$.alerts[].severity	number	CAP info.severity，参考 CAPAlertSeverity
$.alerts[].certainty	number	CAP info.certainty，参考 CAPAlertCertainty
$.alerts[].sent_time	number	发送时间戳（秒）
$.alerts[].effective_time	number	生效时间戳（秒）
$.alerts[].onset_time	number	事件开始时间戳（秒）
$.alerts[].expires_time	number	过期时间戳（秒）
$.alerts[].references	array<string>	CAP references
$.alerts[].areas	array<object>	受影响区域
$.alerts[].language_code	string	当前返回文本的语言编码
$.alerts[].sender_name	string	发布机构名称
$.alerts[].headline	string	标题
$.alerts[].description	string	预警描述
$.alerts[].instruction	string	防御建议或行动指引

CAPAlertArea

JSONPath	类型	说明
$.alerts[].areas[].area_desc	string	区域描述
$.alerts[].areas[].geocodes	array<object>	区域编码
$.alerts[].areas[].polygons	array<object>	多边形范围
$.alerts[].areas[].circles	array<object>	圆形范围
$.alerts[].areas[].altitude	number	CAP altitude，单位为米
$.alerts[].areas[].ceiling	number	CAP ceiling，单位为米

CAPAlertGeocode

JSONPath	类型	说明
$.alerts[].areas[].geocodes[].value_name	string	编码名称
$.alerts[].areas[].geocodes[].value	string	编码值
$.alerts[].areas[].geocodes[].namespace	string	编码命名空间

CAPAlertPolygon

JSONPath	类型	说明
$.alerts[].areas[].polygons[].vertices	array<object>	多边形顶点，字段为 latitude/longitude

CAPAlertCircle

JSONPath	类型	说明
$.alerts[].areas[].circles[].center	object	圆心，字段为 latitude/longitude
$.alerts[].areas[].circles[].radius_km	number	半径，单位为千米

CAPAlertSource

随时可能新增枚举值，代码请做好兼容处理。

Number	Description
1	US National Weather Service
2	Environment and Climate Change Canada

CAPAlertMsgType

Number	Description
1	Alert
2	Update
3	Cancel

CAPAlertCategory

Number	Description
1	Geo
2	Met
3	Safety
4	Security
5	Rescue
6	Fire
7	Health
8	Env
9	Transport
10	Infra
11	CBRNE
12	Other

CAPAlertUrgency

Number	Description
1	Immediate
2	Expected
3	Future
4	Past
5	Unknown

CAPAlertSeverity

Number	Description
1	Extreme
2	Severe
3	Moderate
4	Minor
5	Unknown

CAPAlertCertainty

Number	Description
1	Observed
2	Likely
3	Possible
4	Unlikely
5	Unknown