Sun Moon
https://data.api.xweather.com/sunmoon/The sunmoon endpoint provides sunrise/set, twilight, moon rise/set, and moon phase information for requested locations and timeframes. This endpoint allows the receipt of up to one month of information per request.
Helpful Hints: The moon details in this endpoint are an approximation based on calculated illumination. For the exact time in which each major moon phase occurs (first quarter, full, last quarter, new) please visit the /sunmoon/moonphases endpoint.
Requests
Every request to the endpoint must include one of the supported actions in the url.
https://data.api.xweather.com/sunmoon/{action}?client_id={client_id}&client_secret={client_secret}&{params}Supported Actions
The following actions are supported with the /sunmoon endpoint:
| Action | Description |
|---|---|
| :id | Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more. |
Response
The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.
Properties
timestamp (number)
UNIX timestamp of the time used for calculating info.
dateTimeISO (string)
ISO 8601 date of the time used for calculating info.
loc (object)
The location of the record.
loc.lat (number)
The latitude coordinate of the record.
loc.long (number)
The place or nearest place to the record.
place (object)
Object containing information about the place or nearest place to the record.
place.name (string)
The place or nearest place to the record.
place.state (string)
The state abbreviation in which the response is located. This may be null or an empty string depending on the country.
place.country (string)
The 2 letter ISO-3166 country abbreviation in which the response is located.
profile (object)
Object containing information about the location or event.
profile.tz (string)
Timezone name of the location, such as America/New_York.
sun (object)
Object containing information about the sun.
sun.rise (number)
UNIX timestamp of the sunrise. Null if no sunrise.
sun.riseISO (string)
The ISO 8601 date of the sunrise. Null if no sunrise.
sun.set (number)
The UNIX timestamp of the sunset. Null if no sunset.
sun.setISO (string)
The ISO 8601 date of the sunset. Null if no sunset.
sun.transit (number)
UNIX timestamp of the point the sun is "overhead". Null if no transit.
sun.transitISO (string)
The ISO 8601 date of the point the sun is "overhead". Null if no transit.
sun.midnightSun (boolean)
Set to true if midnight sun (sun not setting), false otherwise
sun.polarNight (boolean)
Set to true if polar night (the sun is not rising), false otherwise
sun.twilight (object)
Object containing information about the sun's twilight.
sun.twilight.civilBegin (number)
UNIX timestamp of the first civil twilight. Null if no civil twilight. Civil twilight is when the sun is 6 degrees below the horizon.
sun.twilight.civilBeginISO (string)
The ISO 8601 date of the first civil twilight. Null if no civil twilight. Civil twilight is when the sun is 6 degrees below the horizon.
sun.twilight.civilEnd (number)
The UNIX timestamp of the last civil twilight. Null if no civil twilight. Civil twilight is when the sun is 6 degrees below the horizon.
sun.twilight.civilEndISO (string)
The ISO 8601 date of the last civil twilight. Null if no civil twilight. Civil twilight is when the sun is 6 degrees below the horizon.
sun.twilight.nauticalBegin (number)
The UNIX timestamp of the first nautical twilight. Null if no nautical twilight. Nautical twilight is when the sun is 12 degrees below the horizon.
sun.twilight.nauticalBeginISO (string)
The ISO 8601 date of the first nautical twilight. Null if no nautical twilight. Nautical twilight is when the sun is 12 degrees below the horizon.
sun.twilight.nauticalEnd (number)
The UNIX timestamp of the last nautical twilight. Null if no nautical twilight. Nautical twilight is when the sun is 12 degrees below the horizon.
sun.twilight.nauticalEndISO (string)
The ISO 8601 date of the last nautical twilight. Null if no nautical twilight. Nautical twilight is when the sun is 12 degrees below the horizon.
sun.twilight.astronomicalBegin (number)
The UNIX timestamp of the first astronomical twilight. Null if no astronomical twilight. Astronomical twilight is when the sun is 18 degrees below the horizon.
sun.twilight.astronomicalBeginISO (string)
The ISO 8601 date of the first astronomical twilight. Null if no astronomical twilight. Astronomical twilight is when the sun is 18 degrees below the horizon.
sun.twilight.astronomicalEnd (number)
The UNIX timestamp of the last astronomical twilight. Null if no astronomical twilight. Astronomical twilight is when the sun is 18 degrees below the horizon.
sun.twilight.astronomicalEndISO (string)
The ISO 8601 date of the last astronomical twilight. Null if no astronomical twilight. Astronomical twilight is when the sun is 18 degrees below the horizon.
moon (object)
Object containing information about the moon.
moon.rise (number)
UNIX timestamp of the moon rise. Null if no moon rise, maybe occurring shortly after midnight the next morning.
moon.riseISO (string)
The ISO 8601 date of the moon rise. Null if no moon rise, maybe occurring shortly after midnight the next morning.
moon.set (number)
The UNIX timestamp of the moon set. Null if no moon set, maybe occurring shortly after midnight the next morning.
moon.setISO (string)
The ISO 8601 date of the moon set. Null if no moon set, maybe occurring shortly after midnight the next morning.
moon.transit (number)
UNIX timestamp of the point the moon is "overhead". Null if no transit, possibly occurring shortly after midnight the next morning.
moon.transitISO (string)
TISO 8601 date of the point the moon is "overhead". Null if no transit, possibly occurring shortly after midnight the next morning.
moon.underfoot (number)
UNIX timestamp of the point the moon is "underfoot". Null if no underfoot, possibly occurring shortly after midnight the next morning.
moon.underfootISO (string)
ISO 8601 date of the point the moon is "underfoot". Null if no underfoot, possibly occurring shortly after midnight the next morning.
moon.phase (object)
Object containing information about the moon's phase.
moon.phase.phase (number)
The phase of the moon, in degrees, with 0.0 being new moon, 0.25 being first quarter/half moon, 0.5 being full moon, and 0.75 being last quarter/half moon.
moon.phase.name (string)
The name of the phase of the moon, such as "Waxing Gibbous".
moon.phase.illum (number)
The illuminated fraction of the moon, from 0.0 to 1.0, with 0.0 being new moon and 1.0 being full moon.
moon.phase.age (number)
The age of the moon, in days, since the last new moon.
moon.phase.angle (number)
The moon phase angle. See https://en.wikipedia.org/wiki/Moon_phase#Phase_angle for more information.
[
{
"timestamp": 1702620000,
"dateTimeISO": "2023-12-15T00:00:00-06:00",
"loc": {
"lat": 44.97997,
"long": -93.26384
},
"place": {
"name": "minneapolis",
"state": "mn",
"country": "us"
},
"profile": {
"tz": "America/Chicago"
},
"sun": {
"rise": 1702647853,
"riseISO": "2023-12-15T07:44:13-06:00",
"set": 1702679527,
"setISO": "2023-12-15T16:32:07-06:00",
"transit": 1702663690,
"transitISO": "2023-12-15T12:08:10-06:00",
"midnightSun": false,
"polarNight": false,
"twilight": {
"civilBegin": 1702645836,
"civilBeginISO": "2023-12-15T07:10:36-06:00",
"civilEnd": 1702681545,
"civilEndISO": "2023-12-15T17:05:45-06:00",
"nauticalBegin": 1702643605,
"nauticalBeginISO": "2023-12-15T06:33:25-06:00",
"nauticalEnd": 1702683776,
"nauticalEndISO": "2023-12-15T17:42:56-06:00",
"astronomicalBegin": 1702641462,
"astronomicalBeginISO": "2023-12-15T05:57:42-06:00",
"astronomicalEnd": 1702685918,
"astronomicalEndISO": "2023-12-15T18:18:38-06:00"
}
},
"moon": {
"rise": 1702658400,
"riseISO": "2023-12-15T10:40:00-06:00",
"set": 1702689720,
"setISO": "2023-12-15T19:22:00-06:00",
"transit": 1702673820,
"transitISO": "2023-12-15T14:57:00-06:00",
"underfoot": 1702628820,
"underfootISO": "2023-12-15T02:27:00-06:00",
"phase": {
"phase": 0.0827,
"name": "waxing crescent",
"illum": 7,
"age": 2.44,
"angle": 0.54
}
}
}
]