Moon

Access Restriction

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

Provides moonrise time, moonset time, moon phase, and hourly altitude/azimuth data.

Moonrise/Moonset

• Errors

Request

GET https://singer.caiyunhub.com/v3/astro/moon

Query Parameters

Name	Required	Default	Range	Description
token	Yes	—	—	API token; see Authentication
longitude	No	0.0	—	Longitude
latitude	No	0.0	—	Latitude
lang	No	zh-Hans	—	Language; see Language Support
days	No	3	1~15	Number of days

Request Example

curl "https://singer.caiyunhub.com/v3/astro/moon?longitude=-74&latitude=40.7&lang=en&days=15&token={token}"

Response Example

{
  "moon": [
    {
      "date": "2024-04-09",
      "rise": "06:53",
      "set": "20:54",
      "phase": 5.7,
      "phase_name": "New Moon"
    },
    // ...
    {
      "date": "2024-04-23",
      "rise": "19:48",
      "set": "05:42",
      "phase": 170.78,
      "phase_name": "Full Moon"
    }
  ]
}

Response Fields

JSONPath	Type	Description
$.moon	array	Moonrise, moonset, and phase data
$.moon[].date	string	Date
$.moon[].rise	string	Rise time, - if not applicable
$.moon[].set	string	Set time, - if not applicable
$.moon[].phase	number	Moon phase angle
$.moon[].phase_name	string	Name of the moon phase

Supported moon phase values in English environment:

Emoji	Phase
🌑	New Moon
🌒	Waxing crescent
🌓	First quarter
🌔	Waxing gibbous
🌕	Full Moon
🌖	Waning gibbous
🌗	Last quarter
🌘	Waning crescent

Moon Altitude/Azimuth

Provides hourly moon altitude and azimuth data.

• Errors

Request

GET https://singer.caiyunhub.com/v3/astro/moon/location

Query Parameters

Name	Required	Default	Range	Description
token	Yes	—	—	API token; see Authentication
longitude	No	0.0	—	Longitude
latitude	No	0.0	—	Latitude
dailystart	No	0	-1	Day offset; -1 starts from yesterday
days	No	1	1~2	Number of days

Request Example

curl "https://singer.caiyunhub.com/v3/astro/moon/location?longitude=116&latitude=39&dailystart=-1&days=2&token={token}"

Response Example

{
  "data": [
    { "timestamp": 1769468400, "altitude": 21.5018, "azimuth": 268.0806 },
    { "timestamp": 1769472000, "altitude": 18.6872, "azimuth": 282.1501 },
    // ...
    { "timestamp": 1769637600, "altitude": 35.81, "azimuth": 225.1094 }
  ]
}

Response Fields

JSONPath	Type	Description
$.data	array	Hourly moon position data
$.data[].timestamp	number	Timestamp
$.data[].altitude	number	Altitude angle
$.data[].azimuth	number	Azimuth angle