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 and Canada. 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

http

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`, `CA`	Region code
`language`	No	`en-US` (US) / `en-CA` (CA)	US: `en-US`; CA: `en-CA`, `fr-CA`	Response text language; unsupported languages fall back to the region default

Request Example

United States:

bash

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

Canada (French):

bash

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

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

json

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

Response Fields

GetAllCAPAlertsResponse

JSONPath	Type	Description
`$.result`	`CAPAlertDownloadResult`	Download result
`$.attributions`	`array<CAPAlertAttribution>`	Data source, license, and attribution metadata

CAPAlertDownloadResult

JSONPath	Type	Description
`$.result.url`	string	Signed GeoJSON download URL
`$.result.updated_at`	number	GeoJSON file update timestamp in seconds

CAPAlertAttribution

Field	Type	Description
`source`	number	Alert source. See CAPAlertSource
`provider`	string	Provider of the alert data or geometry
`source_url`	string	Source URL
`attribution_text`	string	Attribution text intended for display
`license_id`	string	License identifier
`license_url`	string	License URL; omitted when unavailable
`terms_url`	string	Source terms-of-use URL; omitted when unavailable
`applies_to`	string	Attribution scope: `alert_data` for alert data or `geometry` for geometry data

Downloaded File

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

json

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

Downloaded File Fields

FeatureCollection

JSONPath	Type	Description
`$.type`	string	Always `FeatureCollection`
`$.features`	`array<Feature>`	CAP weather alert impact areas
`$.attributions`	`array<CAPAlertAttribution>`	Data source, license, and attribution metadata

Feature

JSONPath	Type	Description
`$.features[].type`	string	Always `Feature`
`$.features[].geometry`	`GeoJSON Geometry`	Alert area geometry. It may be `Polygon` or an approximated circle polygon.
`$.features[].id`	string	Unique identifier for this geometry
`$.features[].properties`	`CAPAlertFeatureProperties`	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<CAPAlertGeocode>`	Area geocodes

Bulk API ​

Request ​

Query Parameters ​

Request Example ​

Response Example ​

Response Fields ​

GetAllCAPAlertsResponse ​

CAPAlertDownloadResult ​

CAPAlertAttribution ​

Downloaded File ​

Downloaded File Fields ​

FeatureCollection ​

Feature ​

CAPAlertFeatureProperties ​