Bulk API

Access Restriction

This API is a premium service available only to enterprise tier developers. Please contact Caiyun Sales to purchase.

TIP

CAP weather alerts are currently supported for the United States. Other countries and regions are being added gradually.

Each request consumes one API call quota.

This API is designed for clients that need to overlay CAP weather alert impact areas on a map. It returns a signed GeoJSON download URL. In the downloaded file, each item in features represents a polygon or circle area of an alert.

• Authentication | Errors | Coverage and Data Granularity

Request:

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

The service generates or reuses a static CAP weather alert GeoJSON file. result.url is a signed download URL, and result.updated_at is the file update timestamp in seconds.

Request parameters:

Field	Type	Required	Description
region_code	string	No	Region code. Defaults to US; currently only US is supported
language	string	No	Response text language. US currently only supports en-US; unsupported languages fall back to en-US

Response

{
  "result": {
    "url": "https://cdn.example.com/dvf/develop/cap-alert/all/US/en-US/latest.geojson?sign=1",
    "updated_at": 1750123200
  }
}

GetAllCAPAlertsResponse

Field	Type	Description
result	CAPAlertDownloadResult object	Download result

CAPAlertDownloadResult

Field	Type	Description
url	string	Signed GeoJSON download URL
updated_at	int64	GeoJSON file update timestamp in seconds

Downloaded File

The GeoJSON file at result.url has the following structure:

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

FeatureCollection

Field	Type	Description
type	string	Always FeatureCollection
features	Feature[]	CAP weather alert impact areas

Feature

Field	Type	Description
type	string	Always Feature
geometry	GeoJSON Geometry	Alert area geometry. It may be Polygon or an approximated circle polygon.
id	string	Unique identifier for this geometry
properties	CAPAlertFeatureProperties	CAP weather alert properties

CAPAlertFeatureProperties

Field	Type	Description
id	string	Unique alert identifier
region_code	string	ISO 3166-1 Alpha-2 code
source	int32	Alert source. See CAPAlertSource
msg_type	int32	CAP msgType. See CAPAlertMsgType
event_name	string	Event name
categories	int32[]	CAP info.category. Currently only the Met type is returned. See CAPAlertCategory
urgency	int32	CAP info.urgency. See CAPAlertUrgency
severity	int32	CAP info.severity. See CAPAlertSeverity
certainty	int32	CAP info.certainty. See CAPAlertCertainty
sent_time	int64	Sent timestamp in seconds
effective_time	int64	Effective timestamp in seconds
onset_time	int64	Onset timestamp in seconds
expires_time	int64	Expiration timestamp in seconds
references	string[]	CAP references
language_code	string	Language code of the returned text
sender_name	string	Sender name
headline	string	Headline
description	string	Alert description
instruction	string	Recommended instructions
area_desc	string	Area description
geocodes	CAPAlertGeocode[]	Area geocodes