Sunrise and Sunset Glow

Access Restriction

This API is a premium service available only to enterprise tier developers. Please contact Caiyun Sales to purchase.

• Error Information

Request

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

Query Parameters

Name	Required	Default	Range	Description
longitude	Yes	—	—	Longitude
latitude	Yes	—	—	Latitude
token	Yes	—	—	API token; see Authentication
image	No	true	true, false	Return layer URLs; false excludes layer-related fields

Request Examples

curl "https://singer.caiyunhub.com/v3/glow/location?longitude=116&latitude=39&token={token}"

curl "https://singer.caiyunhub.com/v3/glow/location?longitude=116&latitude=39&token={token}&image=false"

Response Examples

Default Response (image=true or not specified)

{
  "bbox": {
    "lon": [72, 135],
    "lat": [17, 54]
  },
  "expires_at": 1766703600,
  "evening": {
    "probability": 22,
    "quality": 32,
    "start_time": 1766735488,
    "end_time": 1766747776,
    "probability_layer": "http://meteorology.caiyuncdn.com/dvf/prod/ljweather/image/2025/12/25/22/S_2025122522_20251226_PR.png?auth_key={auth_key}",
    "quality_layer": "http://meteorology.caiyuncdn.com/dvf/prod/ljweather/image/2025/12/25/22/S_2025122522_20251226_QU.png?auth_key={auth_key}",
    "publish_time": 1766700000,
    "predict_date": {
      "year": 2025,
      "month": 12,
      "day": 26
    }
  },
  "morning": {
    "probability": 0,
    "quality": 0,
    "start_time": 0,
    "end_time": 0,
    "probability_layer": "http://meteorology.caiyuncdn.com/dvf/prod/ljweather/image/2025/12/25/10/R_2025122510_20251226_PR.png?auth_key={auth_key}",
    "quality_layer": "http://meteorology.caiyuncdn.com/dvf/prod/ljweather/image/2025/12/25/10/R_2025122510_20251226_QU.png?auth_key={auth_key}",
    "publish_time": 1766656800,
    "predict_date": {
      "year": 2025,
      "month": 12,
      "day": 26
    }
  }
}

Simplified Response (image=false)

When image=false is set, the response does not include bbox, expires_at, probability_layer, and quality_layer fields:

{
  "evening": {
    "probability": 22,
    "quality": 32,
    "start_time": 1766735488,
    "end_time": 1766747776,
    "publish_time": 1766700000,
    "predict_date": {
      "year": 2025,
      "month": 12,
      "day": 26
    }
  },
  "morning": {
    "probability": 0,
    "quality": 0,
    "start_time": 0,
    "end_time": 0,
    "publish_time": 1766656800,
    "predict_date": {
      "year": 2025,
      "month": 12,
      "day": 26
    }
  }
}

Response Fields

Root Object

JSONPath	Type	Description
$.bbox	BBox	Data coverage bounding box (returned only when image=true)
$.expires_at	number	Layer signed URL expiration time (Unix timestamp, seconds; returned only when image=true)
$.evening	GlowInfo	Evening glow information
$.morning	GlowInfo	Morning glow information

BBox

JSONPath	Type	Description
$.bbox.lon	array<number>	Longitude range, format: [min_longitude, max_longitude]
$.bbox.lat	array<number>	Latitude range, format: [min_latitude, max_latitude]

GlowInfo

The paths below use evening; morning has the same fields.

JSONPath	Type	Description
$.evening.probability	number	Occurrence probability, range: 0-100
$.evening.quality	number	Quality score, range: 0-100
$.evening.start_time	number	Start timestamp (Unix timestamp, seconds)
$.evening.end_time	number	End timestamp (Unix timestamp, seconds)
$.evening.probability_layer	string	Probability layer URL (returned only when image=true)
$.evening.quality_layer	string	Quality layer URL (returned only when image=true)
$.evening.publish_time	number	Publication timestamp (Unix timestamp, seconds)
$.evening.predict_date	PredictDate	Forecast date (Beijing Time UTC+8)

PredictDate

JSONPath	Type	Description
$.evening.predict_date.year	number	Year
$.evening.predict_date.month	number	Month
$.evening.predict_date.day	number	Day

Data Coverage

This API covers the China region with the following geographic coordinate ranges:

• Longitude range: [72, 135]
• Latitude range: [17, 54]

Data Update Information

Data Timeliness

Sunrise and sunset glow data only provides the latest batch of data and does not support historical data queries. When data has not been updated, the API will return the previous batch of valid forecast data.

Update Frequency

• Evening Glow: Updated 3 times daily, expected update times are 02:00, 08:00, and 14:00 Beijing Time, providing evening glow forecast data for the current day.
• Morning Glow: Updated 2 times daily, expected update times are 14:00 and 19:00 Beijing Time, providing next-day morning glow forecast data.

Update Time Notice

Update times may be adjusted due to system maintenance or data processing requirements. Please refer to actual updates for specific times.

Notes

• probability_layer and quality_layer are layer image URLs that can be used for visualization
• expires_at is the expiration time of the signed layer URLs and is shared by morning and evening glow; the TTL is 1 hour. Request this API again after expiry to get new URLs