批量获取 API

访问限制

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

TIP

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

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

本接口重点为需要在地图叠加 CAP 气象预警影响范围的客户提供一个方便的批量获取 API。接口返回一个带签名的 GeoJSON 下载地址，下载文件中的 features 每个元素对应一个预警区域的多边形或圆形范围。

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

请求

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

查询参数

参数	必填	默认值	取值范围	说明
token	是	—	—	API 认证凭证，详见 认证与鉴权
region_code	否	US	US、CA	地区编码
language	否	en-US（US）/ en-CA（CA）	US：en-US；CA：en-CA、fr-CA	返回文本语言；不支持的语言会回落到对应地区的默认语言

请求示例

美国：

curl "https://singer.caiyunhub.com/v3/cap_alert/all?token={token}&region_code=US&language=en-US"

加拿大（法语）：

curl "https://singer.caiyunhub.com/v3/cap_alert/all?token={token}&region_code=CA&language=fr-CA"

接口会在服务端生成或复用 CAP 气象预警 GeoJSON 静态文件，响应中的 result.url 是带签名的下载地址， result.updated_at 是该文件的更新时间戳（秒）。

响应示例

{
  "result": {
    "url": "https://cdn.example.com/dvf/develop/cap-alert/all/US/en-US/latest.geojson?sign=1",
    "updated_at": 1750123200
  },
  "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"
    }
  ]
}

响应字段

GetAllCAPAlertsResponse

JSONPath	类型	说明
$.result	CAPAlertDownloadResult	下载结果
$.attributions	array<CAPAlertAttribution>	数据来源、许可证及署名信息

CAPAlertDownloadResult

JSONPath	类型	说明
$.result.url	string	带签名的 GeoJSON 下载地址
$.result.updated_at	number	GeoJSON 文件更新时间戳（秒）

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 表示几何信息

下载文件结构

result.url 指向的 GeoJSON 文件结构如下：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-118.45, 34.11],
            [-118.10, 34.10],
            [-118.12, 33.90],
            [-118.45, 34.11]
          ]
        ]
      },
      "id": "nws-alert-1:area:0:polygon:0",
      "properties": {
        "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": [],
        "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.",
        "area_desc": "Los Angeles",
        "geocodes": [
          {
            "value_name": "UGC",
            "value": "CAC037",
            "namespace": "NWS_UGC"
          }
        ]
      }
    }
  ],
  "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"
    }
  ]
}

下载文件字段

FeatureCollection

JSONPath	类型	说明
$.type	string	固定为 FeatureCollection
$.features	array<Feature>	CAP 气象预警影响范围
$.attributions	array<CAPAlertAttribution>	数据来源、许可证及署名信息

Feature

JSONPath	类型	说明
$.features[].type	string	固定为 Feature
$.features[].geometry	GeoJSON Geometry	预警区域范围，可能为 Polygon 或圆形近似多边形
$.features[].id	string	当前范围的唯一标识
$.features[].properties	CAPAlertFeatureProperties	CAP 气象预警属性

CAPAlertFeatureProperties

JSONPath	类型	说明
$.features[].properties.id	string	预警唯一标识
$.features[].properties.region_code	string	ISO 3166-1 Alpha-2 code
$.features[].properties.source	number	预警来源机构，参考 CAPAlertSource
$.features[].properties.msg_type	number	CAP msgType，参考 CAPAlertMsgType
$.features[].properties.event_name	string	事件名称
$.features[].properties.categories	array<number>	CAP info.category，目前只返回 Met 类型，参考 CAPAlertCategory
$.features[].properties.urgency	number	CAP info.urgency，参考 CAPAlertUrgency
$.features[].properties.severity	number	CAP info.severity，参考 CAPAlertSeverity
$.features[].properties.certainty	number	CAP info.certainty，参考 CAPAlertCertainty
$.features[].properties.sent_time	number	发送时间戳（秒）
$.features[].properties.effective_time	number	生效时间戳（秒）
$.features[].properties.onset_time	number	事件开始时间戳（秒）
$.features[].properties.expires_time	number	过期时间戳（秒）
$.features[].properties.references	array<string>	CAP references
$.features[].properties.language_code	string	当前返回文本的语言编码
$.features[].properties.sender_name	string	发布机构名称
$.features[].properties.headline	string	标题
$.features[].properties.description	string	预警描述
$.features[].properties.instruction	string	防御建议或行动指引
$.features[].properties.area_desc	string	区域描述
$.features[].properties.geocodes	array<CAPAlertGeocode>	区域编码