单点查询 API

访问限制

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

TIP

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

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

• 认证与鉴权 | 错误信息 | 支持范围与数据粒度

调用方式:

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

请求参数:

Field	Type	Required	Description
longitude	float	是	经度
latitude	float	是	纬度
language	string	否	返回文本语言，默认值为 zh-CN

返回结构

{
  "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

Field	Type	Description
alerts	CAPAlert 数组	CAP 气象预警记录列表

CAPAlert

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

CAPAlertArea

Field	Type	Description
area_desc	string	区域描述
geocodes	CAPAlertGeocode 数组	区域编码
polygons	CAPAlertPolygon 数组	多边形范围
circles	CAPAlertCircle 数组	圆形范围
altitude	double	CAP altitude，单位为米
ceiling	double	CAP ceiling，单位为米

CAPAlertGeocode

Field	Type	Description
value_name	string	编码名称
value	string	编码值
namespace	string	编码命名空间

CAPAlertPolygon

Field	Type	Description
vertices	LatLng 数组	多边形顶点，字段为 latitude/longitude

CAPAlertCircle

Field	Type	Description
center	LatLng	圆心，字段为 latitude/longitude
radius_km	double	半径，单位为千米

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