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.

• Errors | Coverage and Data Granularity

Request

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

Query Parameters

Name	Required	Default	Range	Description
token	Yes	—	—	API token; see Authentication
region_code	No	US	US	Region code; currently only US is supported
language	No	en-US	en-US	Response text language; unsupported languages fall back to en-US

Request Example

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.

Response Example

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

Response Fields

GetAllCAPAlertsResponse

JSONPath	Type	Description
$.result	object	Download result

CAPAlertDownloadResult

JSONPath	Type	Description
$.result.url	string	Signed GeoJSON download URL
$.result.updated_at	number	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"
          }
        ]
      }
    }
  ]
}

Downloaded File Fields

FeatureCollection

JSONPath	Type	Description
$.type	string	Always FeatureCollection
$.features	array<object>	CAP weather alert impact areas

Feature

JSONPath	Type	Description
$.features[].type	string	Always Feature
$.features[].geometry	object	Alert area geometry. It may be Polygon or an approximated circle polygon.
$.features[].id	string	Unique identifier for this geometry
$.features[].properties	object	CAP weather alert properties

CAPAlertFeatureProperties

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