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.

• Authentication | Errors | Coverage and Data Granularity

Request:

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

Request parameters:

Field	Type	Required	Description
longitude	float	Yes	Longitude
latitude	float	Yes	Latitude
language	string	No	Response text language, defaults to zh-CN

Response

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

CAPAlerts

Field	Type	Description
alerts	CAPAlert[]	CAP weather alert records

CAPAlert

Field	Type	Description
id	string	Unique alert identifier. Do not parse it for business logic.
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, preferring the selected response language
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
areas	CAPAlertArea[]	Affected areas
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

CAPAlertArea

Field	Type	Description
area_desc	string	Area description
geocodes	CAPAlertGeocode[]	Area geocodes
polygons	CAPAlertPolygon[]	Polygon geometries
circles	CAPAlertCircle[]	Circle geometries
altitude	double	CAP altitude, in meters
ceiling	double	CAP ceiling, in meters

CAPAlertGeocode

Field	Type	Description
value_name	string	Geocode name
value	string	Geocode value
namespace	string	Geocode namespace

CAPAlertPolygon

Field	Type	Description
vertices	LatLng[]	Polygon vertices with latitude/longitude fields

CAPAlertCircle

Field	Type	Description
center	LatLng	Circle center with latitude/longitude fields
radius_km	double	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