Location 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.

• Errors | Coverage and Data Granularity

Request

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

Query Parameters

Name	Required	Default	Range	Description
token	Yes	—	—	API token; see Authentication
longitude	Yes	—	—	Longitude
latitude	Yes	—	—	Latitude
language	No	zh-CN	BCP 47 language tag	Response text language

Request Example

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

Response Example

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

Response Fields

CAPAlerts

JSONPath	Type	Description
$.alerts	array<object>	CAP weather alert records

CAPAlert

JSONPath	Type	Description
$.alerts[].id	string	Unique alert identifier. Do not parse it for business logic.
$.alerts[].region_code	string	ISO 3166-1 Alpha-2 code
$.alerts[].source	number	Alert source. See CAPAlertSource
$.alerts[].msg_type	number	CAP msgType. See CAPAlertMsgType
$.alerts[].event_name	string	Event name, preferring the selected response language
$.alerts[].categories	array<number>	CAP info.category. Currently only the Met type is returned. See CAPAlertCategory
$.alerts[].urgency	number	CAP info.urgency. See CAPAlertUrgency
$.alerts[].severity	number	CAP info.severity. See CAPAlertSeverity
$.alerts[].certainty	number	CAP info.certainty. See CAPAlertCertainty
$.alerts[].sent_time	number	Sent timestamp in seconds
$.alerts[].effective_time	number	Effective timestamp in seconds
$.alerts[].onset_time	number	Onset timestamp in seconds
$.alerts[].expires_time	number	Expiration timestamp in seconds
$.alerts[].references	array<string>	CAP references
$.alerts[].areas	array<object>	Affected areas
$.alerts[].language_code	string	Language code of the returned text
$.alerts[].sender_name	string	Sender name
$.alerts[].headline	string	Headline
$.alerts[].description	string	Alert description
$.alerts[].instruction	string	Recommended instructions

CAPAlertArea

JSONPath	Type	Description
$.alerts[].areas[].area_desc	string	Area description
$.alerts[].areas[].geocodes	array<object>	Area geocodes
$.alerts[].areas[].polygons	array<object>	Polygon geometries
$.alerts[].areas[].circles	array<object>	Circle geometries
$.alerts[].areas[].altitude	number	CAP altitude, in meters
$.alerts[].areas[].ceiling	number	CAP ceiling, in meters

CAPAlertGeocode

JSONPath	Type	Description
$.alerts[].areas[].geocodes[].value_name	string	Geocode name
$.alerts[].areas[].geocodes[].value	string	Geocode value
$.alerts[].areas[].geocodes[].namespace	string	Geocode namespace

CAPAlertPolygon

JSONPath	Type	Description
$.alerts[].areas[].polygons[].vertices	array<object>	Polygon vertices with latitude/longitude fields

CAPAlertCircle

JSONPath	Type	Description
$.alerts[].areas[].circles[].center	object	Circle center with latitude/longitude fields
$.alerts[].areas[].circles[].radius_km	number	Radius in kilometers

CAPAlertSource

New enum values may be added at any time. Code should handle unknown values.

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