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 and Canada. 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. Current data provides en-US, en-CA, and fr-CA; if the requested language is unavailable, the first language provided by the source is returned.

Request Example

United States:

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

Canada (French):

curl "https://singer.caiyunhub.com/v3/cap_alert/location?token={token}&longitude=-73.5673&latitude=45.5017&language=fr-CA"

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

CAPAlerts

JSONPath	Type	Description
$.alerts	array<CAPAlert>	CAP weather alert records
$.attributions	array<CAPAlertAttribution>	Data source, license, and attribution metadata

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

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<CAPAlertArea>	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<CAPAlertGeocode>	Area geocodes
$.alerts[].areas[].polygons	array<CAPAlertPolygon>	Polygon geometries
$.alerts[].areas[].geocode_polygons	array<CAPAlertGeocodePolygon>	Polygon geometries supplemented from area geocodes
$.alerts[].areas[].circles	array<CAPAlertCircle>	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<LatLng>	Polygon vertices with latitude/longitude fields

CAPAlertGeocodePolygon

JSONPath	Type	Description
$.alerts[].areas[].geocode_polygons[].rings	array<CAPAlertPolygonRing>	Polygon rings. The first is the exterior; subsequent rings are holes.

CAPAlertPolygonRing

JSONPath	Type	Description
$.alerts[].areas[].geocode_polygons[].rings[].vertices	array<LatLng>	Ring vertices with latitude/longitude fields

CAPAlertCircle

JSONPath	Type	Description
$.alerts[].areas[].circles[].center	LatLng	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