单点查询 API

访问限制

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

TIP

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

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

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

请求

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

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权
longitude	是	—	—	经度
latitude	是	—	—	纬度
language	否	zh-CN	BCP 47 语言标签	返回文本语言；当前数据提供 en-US、en-CA 和 fr-CA，请求语言不可用时返回数据源提供的首个可用语言

请求示例

美国：

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

加拿大（法语）：

curl "https://singer.caiyunhub.com/v3/cap_alert/location?token={token}&longitude=-73.5673&latitude=45.5017&language=fr-CA"

响应示例

{
  "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."
    }
  ],
  "attributions": [
    {
      "source": 1,
      "provider": "National Weather Service (NWS)",
      "source_url": "https://api.weather.gov/alerts/active.atom",
      "attribution_text": "Source: National Weather Service (NWS).",
      "license_id": "public-domain",
      "license_url": "https://www.weather.gov/disclaimer",
      "applies_to": "alert_data"
    }
  ]
}

响应字段

CAPAlerts

JSONPath	类型	说明
$.alerts	array<CAPAlert>	CAP 气象预警记录列表
$.attributions	array<CAPAlertAttribution>	数据来源、许可证及署名信息

CAPAlertAttribution

字段	类型	说明
source	number	预警来源机构，参考 CAPAlertSource
provider	string	数据或几何信息提供方
source_url	string	数据源地址
attribution_text	string	用于展示的署名文本
license_id	string	许可证标识
license_url	string	许可证地址，未提供时不返回该字段
terms_url	string	数据源使用条款地址，未提供时不返回该字段
applies_to	string	署名信息的适用对象：alert_data 表示预警数据，geometry 表示几何信息

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<CAPAlertArea>	受影响区域
$.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<CAPAlertGeocode>	区域编码
$.alerts[].areas[].polygons	array<CAPAlertPolygon>	多边形范围
$.alerts[].areas[].geocode_polygons	array<CAPAlertGeocodePolygon>	根据区域编码补充的多边形范围
$.alerts[].areas[].circles	array<CAPAlertCircle>	圆形范围
$.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<LatLng>	多边形顶点，字段为 latitude/longitude

CAPAlertGeocodePolygon

JSONPath	类型	说明
$.alerts[].areas[].geocode_polygons[].rings	array<CAPAlertPolygonRing>	多边形环，首环为外边界，后续环为内洞

CAPAlertPolygonRing

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

CAPAlertCircle

JSONPath	类型	说明
$.alerts[].areas[].circles[].center	LatLng	圆心，字段为 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