IPGeolocation.io · Schema

AstronomyTimeSeriesEntry

Astronomical data for a single calendar day within the time series response. Contains event times for sunrise, sunset, moonrise, moonset, twilight phases, solar noon, and day length. Note: Real-time positional data (sun/moon altitude, azimuth, distance, parallactic angle, illumination percentage, and moon angle) is not included in time series entries.

GeocodingIP GeolocationIP IntelligenceIP SecurityASN LookupAbuse ContactTimezoneAstronomyUser AgentThreat IntelligencePublic APIs

Properties

Name	Type	Description
date	string	The calendar date for this entry, in `yyyy-MM-dd` format.
mid_night	string	Astronomical midnight (nadir) for the given date.
night_end	string	End of night / start of astronomical twilight in the morning.
morning	object	Twilight phase times for either the morning (pre-sunrise) or evening (post-sunset) period. Includes astronomical, nautical, and civil twilight windows, as well as blue hour and golden hour windows com
sunrise	string	Time at which the sun rises, in `HH:mm` format. Returns `"-:-"` if the sun does not rise on this date.
sunset	string	Time at which the sun sets, in `HH:mm` format. Returns `"-:-"` if the sun does not set on this date.
evening	object	Twilight phase times for either the morning (pre-sunrise) or evening (post-sunset) period. Includes astronomical, nautical, and civil twilight windows, as well as blue hour and golden hour windows com
night_begin	string	Start of night / end of astronomical twilight in the evening.
sun_status	string	Current state of the sun relative to the horizon. See `AstronomyData.sun_status` for possible values.
solar_noon	string	Time when the sun is at its highest point in the sky.
day_length	string	Total daylight duration from sunrise to sunset, in `HH:mm` format.
moon_phase	string	The phase of the moon on this date.
moonrise	string	Time at which the moon rises, in `HH:mm` format. Returns `"-:-"` if the moon does not rise on this date.
moonset	string	Time at which the moon sets, in `HH:mm` format. Returns `"-:-"` if the moon does not set on this date.
moon_status	string	Current state of the moon relative to the horizon. See `AstronomyData.moon_status` for possible values.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/ipgeolocation/refs/heads/main/json-schema/astronomy-astronomy-time-series-entry-schema.json",
  "title": "AstronomyTimeSeriesEntry",
  "description": "Astronomical data for a single calendar day within the time series\nresponse.\n\nContains event times for sunrise, sunset, moonrise, moonset,\ntwilight phases, solar noon, and day length.\n\nNote: Real-time positional data (sun/moon altitude, azimuth,\ndistance, parallactic angle, illumination percentage, and moon\nangle) is not included in time series entries.\n",
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "The calendar date for this entry, in `yyyy-MM-dd` format.",
      "example": "2026-03-18"
    },
    "mid_night": {
      "type": "string",
      "description": "Astronomical midnight (nadir) for the given date.",
      "example": "00:06"
    },
    "night_end": {
      "type": "string",
      "description": "End of night / start of astronomical twilight in the morning.",
      "example": "04:49"
    },
    "morning": {
      "type": "object",
      "description": "Twilight phase times for either the morning (pre-sunrise) or evening\n(post-sunset) period.\n\nIncludes astronomical, nautical, and civil twilight windows, as well\nas blue hour and golden hour windows commonly used in photography.\n\nAll times are in `HH:mm` format by default. When the `time_zone`\nparameter is provided, times are returned as full date-time values\nin `yyyy-MM-dd HH:mm` format.\n",
      "properties": {
        "astronomical_twilight_begin": {
          "type": "string",
          "description": "Start of astronomical twilight. In the morning, this marks the\nend of night; in the evening, this marks the start of night sky.\n",
          "example": "04:49"
        },
        "astronomical_twilight_end": {
          "type": "string",
          "description": "End of astronomical twilight.",
          "example": "05:21"
        },
        "nautical_twilight_begin": {
          "type": "string",
          "description": "Start of nautical twilight, when the horizon first becomes visible.\n",
          "example": "05:21"
        },
        "nautical_twilight_end": {
          "type": "string",
          "description": "End of nautical twilight.",
          "example": "05:53"
        },
        "civil_twilight_begin": {
          "type": "string",
          "description": "Start of civil twilight, when there is enough light for outdoor\nactivities without artificial lighting.\n",
          "example": "05:53"
        },
        "civil_twilight_end": {
          "type": "string",
          "description": "End of civil twilight.",
          "example": "06:20"
        },
        "blue_hour_begin": {
          "type": "string",
          "description": "Start of the blue hour, a period of soft diffused light with a\nblue color tone.\n",
          "example": "05:42"
        },
        "blue_hour_end": {
          "type": "string",
          "description": "End of the blue hour.",
          "example": "06:03"
        },
        "golden_hour_begin": {
          "type": "string",
          "description": "Start of the golden hour, a period of warm low-angle light\nfavored by photographers.\n",
          "example": "06:03"
        },
        "golden_hour_end": {
          "type": "string",
          "description": "End of the golden hour.",
          "example": "06:57"
        }
      }
    },
    "sunrise": {
      "type": "string",
      "description": "Time at which the sun rises, in `HH:mm` format. Returns `\"-:-\"`\nif the sun does not rise on this date.\n",
      "example": "06:20"
    },
    "sunset": {
      "type": "string",
      "description": "Time at which the sun sets, in `HH:mm` format. Returns `\"-:-\"`\nif the sun does not set on this date.\n",
      "example": "19:00"
    },
    "evening": {
      "type": "object",
      "description": "Twilight phase times for either the morning (pre-sunrise) or evening\n(post-sunset) period.\n\nIncludes astronomical, nautical, and civil twilight windows, as well\nas blue hour and golden hour windows commonly used in photography.\n\nAll times are in `HH:mm` format by default. When the `time_zone`\nparameter is provided, times are returned as full date-time values\nin `yyyy-MM-dd HH:mm` format.\n",
      "properties": {
        "astronomical_twilight_begin": {
          "type": "string",
          "description": "Start of astronomical twilight. In the morning, this marks the\nend of night; in the evening, this marks the start of night sky.\n",
          "example": "04:49"
        },
        "astronomical_twilight_end": {
          "type": "string",
          "description": "End of astronomical twilight.",
          "example": "05:21"
        },
        "nautical_twilight_begin": {
          "type": "string",
          "description": "Start of nautical twilight, when the horizon first becomes visible.\n",
          "example": "05:21"
        },
        "nautical_twilight_end": {
          "type": "string",
          "description": "End of nautical twilight.",
          "example": "05:53"
        },
        "civil_twilight_begin": {
          "type": "string",
          "description": "Start of civil twilight, when there is enough light for outdoor\nactivities without artificial lighting.\n",
          "example": "05:53"
        },
        "civil_twilight_end": {
          "type": "string",
          "description": "End of civil twilight.",
          "example": "06:20"
        },
        "blue_hour_begin": {
          "type": "string",
          "description": "Start of the blue hour, a period of soft diffused light with a\nblue color tone.\n",
          "example": "05:42"
        },
        "blue_hour_end": {
          "type": "string",
          "description": "End of the blue hour.",
          "example": "06:03"
        },
        "golden_hour_begin": {
          "type": "string",
          "description": "Start of the golden hour, a period of warm low-angle light\nfavored by photographers.\n",
          "example": "06:03"
        },
        "golden_hour_end": {
          "type": "string",
          "description": "End of the golden hour.",
          "example": "06:57"
        }
      }
    },
    "night_begin": {
      "type": "string",
      "description": "Start of night / end of astronomical twilight in the evening.",
      "example": "20:31"
    },
    "sun_status": {
      "type": "string",
      "description": "Current state of the sun relative to the horizon. See\n`AstronomyData.sun_status` for possible values.\n",
      "example": "-"
    },
    "solar_noon": {
      "type": "string",
      "description": "Time when the sun is at its highest point in the sky.",
      "example": "12:40"
    },
    "day_length": {
      "type": "string",
      "description": "Total daylight duration from sunrise to sunset, in `HH:mm` format.",
      "example": "12:40"
    },
    "moon_phase": {
      "type": "string",
      "description": "The phase of the moon on this date.",
      "enum": [
        "NEW_MOON",
        "WAXING_CRESCENT",
        "FIRST_QUARTER",
        "WAXING_GIBBOUS",
        "FULL_MOON",
        "WANING_GIBBOUS",
        "LAST_QUARTER",
        "WANING_CRESCENT"
      ],
      "example": "WAXING_CRESCENT"
    },
    "moonrise": {
      "type": "string",
      "description": "Time at which the moon rises, in `HH:mm` format. Returns `\"-:-\"`\nif the moon does not rise on this date.\n",
      "example": "08:45"
    },
    "moonset": {
      "type": "string",
      "description": "Time at which the moon sets, in `HH:mm` format. Returns `\"-:-\"`\nif the moon does not set on this date.\n",
      "example": "22:10"
    },
    "moon_status": {
      "type": "string",
      "description": "Current state of the moon relative to the horizon. See\n`AstronomyData.moon_status` for possible values.\n",
      "example": "-"
    }
  }
}