This article aims to provide a more in-depth guide to IPGeolocation.io’s Free Astronomy API. We’ll discuss how the sunrise, sunset, moonrise, moonset, and other celestial data provided by the astronomy API can be a great source for developers to build very handy applications. 

IPGeolocation.io’s Astronomy API provides sun and moon related data along with location information for the current or a specific date. As the name suggests, IPGeolocation.io’s Astronomy API can be queried for not just an IP address, but also for a given time zone, location coordinates, or a location address as well. It includes timings for sunrise, sunset, moonrise, moonset, sun azimuth, moon azimuth, sun altitude, moon altitude, sun distance from Earth, and moon distance from Earth, for the location and date provided. To better say, the API returns timing and positional data for the sun and moon, not just limited to sun rise and sun set times.

The response comes in JSON format by default, but XML formatted response can also be queried. It includes a location object containing geolocation information for the queried way (i.e., by IP, by coordinates, etc.) and an astronomy object. The astronomy object contains the following fields:

• Date and times: date, current_time, sunrise, sunset, solar_noon, day_length.
• Twilight and hour periods: Nested objects for morning and evening times for astronomical, nautical, and civil twilight, as well as blue hour and golden hour periods.
• Sun Position: sun_altitude, sun_azimuth, sun_distance.
• Moon Info: moon_phase (e.g., FULL_MOON), moonrise, moonset, moon_altitude, moon_azimuth, moon_distance, moon_illumination_percentage, etc.

These fields provide you with precise data about the sun and the moon’s different states. Because of its precision using advanced astronomical algorithms, this data is accurate enough for applications like solar panel orientation, outdoor planning, and scientific research.

API Endpoint and Integrations

Our astronomy API has mainly two endpoints to query astronomy events: one is /astronomy and the other is /astronomy/timeSeries. These endpoints can be queried in multiple ways depending on your application needs. Here are the quick ways to get started:

By IP Address: If you call the API endpoint without any query parameter, it will fetch the user’s IP address and return the IP location information along with the astronomy info for the current date. Alternatively, any IPv4 or IPv6 address can also be provided as a query parameter (i.e., &ip=8.8.8.8).

curl 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&ip=8.8.8.8'

By geo-coordinates: If you have GPS coordinates, you can feed the API to get the astronomy facts as well.

curl 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&lat=40.76473&long=-74.00084'

By Physical address/location: Use location=<string-address> to get a physical location's astronomy data. 

curl 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&location=New%20York%2C%20US'

By timezone name: Our Astronomy API provides all types of date and time data for the searched parameter. If you want to get these dates according to a specific IANA timezone, you can provide the timezone identifier as a query parameter (i.e., time_zone=<timezone-name>).

By date: By default, our API returns astronomy data for the current date. To get the historical or future astronomical data, pass the date in the query parameter as date=<yyyy-MM-dd>.

By elevation height: Since sunrise, sunset, moonrise, and moonset times deviate when elevation above sea level increases, so do other dependent fields change. You can provide this elevation height (artificial height above the sea level) in the query parameter elevation=<height-in-meters>. This can either be provided with coordinates or the location parameter. In the following example, this elevation is adding to the sunset time for Dubai, UAE.

curl 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&location=Dubai%2C%20UAE&elevation=800'

Time Series: Our Astronomy API is equipped with the facility to provide up to 90 days of astronomy information at once. /astronomy/timeSeries endpoint accepts date range in query parameters dateStart=<yyyy-MM-dd> and dateEnd=<yyyy-MM-dd>.

curl 'https://api.ipgeolocation.io/v2/astronomy/timeSeries?apiKey=API_KEY&dateStart=2025-06-16&dateEnd=2025-06-18&lat=40.76473&long=-74.00084'

By default, responses are returned in JSON format; however, XML formatted response can also be fetched by appending the query parameter &output=xml. Here’s a sample JSON response for the provided IP address as a query parameter:

{ "ip": "8.8.8.8", "location": { "continent_code": "NA", "continent_name": "North America", "country_code2": "US", "country_code3": "USA", "country_name": "United States", "country_name_official": "United States of America", "is_eu": false, "state_prov": "California", "state_code": "US-CA", "district": "Santa Clara", "city": "Mountain View", "zipcode": "94043-1351", "latitude": "37.42240", "longitude": "-122.08421", "locality": "Charleston Terrace", "elevation": "3" }, "astronomy": { "date": "2025-10-15", "current_time": "05:12:14.643", "mid_night": "00:54", "night_end": "05:50", "morning": { "astronomical_twilight_begin": "05:50", "astronomical_twilight_end": "06:20", "nautical_twilight_begin": "06:20", "nautical_twilight_end": "06:50", "civil_twilight_begin": "06:50", "civil_twilight_end": "07:16", "blue_hour_begin": "06:40", "blue_hour_end": "07:00", "golden_hour_begin": "07:00", "golden_hour_end": "07:52" }, "sunrise": "07:16", "sunset": "18:31", "evening": { "golden_hour_begin": "17:55", "golden_hour_end": "18:46", "blue_hour_begin": "18:46", "blue_hour_end": "19:07", "civil_twilight_begin": "18:31", "civil_twilight_end": "18:56", "nautical_twilight_begin": "18:56", "nautical_twilight_end": "19:27", "astronomical_twilight_begin": "19:27", "astronomical_twilight_end": "19:57" }, "night_begin": "19:57", "sun_status": "-", "solar_noon": "12:53", "day_length": "11:14", "sun_altitude": -25.43835840637013, "sun_distance": 149209891.8470185, "sun_azimuth": 81.22124929376326, "moon_phase": "LAST_QUARTER", "moonrise": "01:28", "moonset": "15:56", "moon_status": "-", "moon_altitude": 41.4723567294689, "moon_distance": 384909.711740241, "moon_azimuth": 96.7467620565339, "moon_parallactic_angle": -56.74263647967493, "moon_illumination_percentage": "-31.59", "moon_angle": 291.60785478793815 } }

At IPGeolocation.io, we put our efforts to ease the developers, and thus we have developed Client Libraries/SDKs for accessing the API. These SDKs are equipped to query not just the Astronomy API, but all other APIs provided by IPGeolocation.io, i.e., IP Location API, IP Security API, IP Abuse Contact API, and ASN API, etc. These are all up-to-date with the latest available version of API api.ipgeolocation.io/v2/. Here are the quick links to the SDKs documentation.

• IP Geolocation API Python SDK | Github
• IP Geolocation API Java SDK | Github
• IP Geolocation API C-Sharp dotNet SDK | Github
• IP Geolocation API PHP SDK | Github
• IP Geolocation API Typescript SDK | Github
• IP Geolocation API Javascript SDK | Github
• IP Geolocation API JQuery SDK | Github

Furthermore, a dedicated client-side Plugin for the Astronomy API is also available for easy implementation for web applications. 

Interpretation on Response Fields

In the JSON response by Astronomy API, there are mainly two objects:

location: This includes the location information (city, state, country, latitude, longitude) for the given ip address, location string, or coordinates.

astronomy: Here’re brief details about the astronomy object fields:

Sun Related fields

• sunrise: It is the time, when the upper limb (top edge) of the sun firstly appears upon the horizon in the morning. 
• sunset: It is the time, when the top edge of the sun completely disappears under the horizon in the evening. 
• day_length: The total time between the sunrise time and the sunset time.

• solar_noon: It is the time when the sun is at maximum altitude in the sky with reference to the current location. At this moment, the Sun appears towards south as seen from Northern Hemisphere and appears towards north as seen from the Southern Hemisphere. The Sun also aligns the local meridian — the line passing through north and south poles. Shadows at this time are at the shortest length. 
• sun_altitude: The angle of the sun above horizon in degrees, while negative value means the sun is below horizon. 

• sun_azimuth: The compass direction of the sun measured in degrees, clockwise from true north.

sun_distance: The distance of the sun from the center of the earth in kiliometers.

Twilight Period fields

The Twilight period is the time between full daylight and dark night, when the sunlight is scattered in the sky, causing the light to diffuse. This duration happens at both sunrise and sunset times and has the following types based on the sun’s angle with relation to the horizon:

• astronomical_twilight: This is the time boundary for the natural light. Astronomers at this time gain the darkest sky in the night and lose it in the morning.
  • Begin (morning): When the sun rises to 18° below the horizon in the morning before dawn.
  • End (evening): When the sun sinks to 18° below the horizon in the evening after dusk.
• nautical_twilight: At the nautical twilight period, the horizon is faintly visible. This time is particularly helpful for sailors at sea when it comes to celestial navigation.
  • Begin (morning): When the sun rises to 12° below the horizon in the morning before dawn.
  • End (evening): When the sun sinks to 12° below the horizon in the evening after dusk.
• civil_twilight: At the civil twilight period, enough light is there for outdoor activities. Street lights are also turned on/off during this period. The end of civil twilight in the morning marks the sunrise, and the start of the civil twilight in the evening marks the sunset.
  • Begin (morning): When the sun rises to 6° below the horizon in the morning before dawn.
  • End (evening): When the sun sinks to 6° below the horizon in the evening after dusk.
• blue_hour: The blue hour, also referred to as the magic hour, is popular amongst photographers for the cool, calming blue-toned light scattered in the sky for beautiful and high-quality pictures. This typically spans around -6° to -4° below the horizon.
  • Morning: In the morning, blue hour happens at the end of nautical twilight and in between civil twilight before sunrise starts.
  • Evening: In the evening, blue hour happens after sunset, in the civil twilight period, and ends at the start of nautical twilight.
• golden_hour: As the name suggests, it is the time when golden, yellowish light is scattered in the sky. This duration is also considered a good time for photographers to take impressive photos. This duration spans around 6° above the horizon to -4° below the horizon.
  • Morning: In the morning, golden hour happens during civil twilight, until the sun rises to a certain height.
  • Evening: In the evening, golden hour happens when the sun is at a particular height, until it drops to civil twilight end.

Here, astronomical twilight end and nautical twilight start; nautical twilight end and civil twilight start; civil twilight end and sunrise times overlap during sunrise and vice versa. These time values differ at large around the poles, resulting in the twilight periods to span for weeks or even months instead of minutes. 

Night Marking fields

• night_begin: This is the moment when astronomical twilight ends in the evening and the sky becomes fully dark. This is the perfect time for astronomers to start their celestial analysis or for sky-watchers to enjoy the stars sparkling in the sky.
• mid_night: This is the halfway between the sunrise and sunset time. This midnight time may differ from the clock midnight time, which is 12 A.M.
• night_end: This is the time when astronomical twilight starts in the morning and the first faint lights start to spread around the sky before dawn.

Moon Related fields

The moon does not rise and set at the same time in a day. Its time usually shifts by 50 minutes daily. Like the sun, the moon's appearance is also affected by atmospheric refraction, resulting in a slightly earlier appearance of the moon.

• moonrise: The moment when the upper edge of the moon firstly appears above the horizon.
• moonset: The moment when the upper edge of the moon sinks below the horizon.
• moon_phase: The current illuminated fraction of the moon as seen from the earth. This is caused by the relative positions of the sun, the moon, and the Earth. These positions are categorized into 8 phases: New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Third Quarter, and Waning Crescent. These phases lasts around 29.5 days making the lunar calendar month.
• moon_illumination_percentage: Moon Illumination percentage is the fraction of the moon’s surface illuminated by the sun represented as percentage. It helps in identifying the brightness of the moon on earth.
• moon_altitude: The angle of the moon above the horizon in degrees. It’s positive value shows, the moon is visible and is above horizon; and negative value means, the moon is not visible and is below horizon.
• moon_azimuth: The compass direction of the moon measured in degrees, clockwise from true north. It is useful for the placement of the telescope for lunar events observation.
• moon_distance: The distance of the moon from the center of the earth in kilometers. This distance varies due to the eliptical orbit of the moon around the earth.
• moon_parallactic_angle: It is the angle between the moon’s celestial north pole and the vertical line also called the zenith direction right above the observer’s location. This represents the tilted value of the moon as seen from the a point on earth.
• moon_angle: It is representing the illuminated portion of the moon in relation to the sun-earth line.

A visualization of the Moon Phases change with the illumination percentage and elapsed days is presented below:

Other fields

• sun_status: This represents the current visibility status of the Sun relative to the horizon. In some regions of Earth and during certain seasons, especially near the Arctic and Antarctic Circles, the Sun can remain above the horizon for many days or weeks (the “Midnight Sun” phenomenon) or stay below the horizon for an extended period (Polar Night).

In such cases, the sunrise and sunset values will be shown as "-:-", and sun_status will display either:

• "Always above the twilight angle": meaning the Sun never dips far enough below the horizon to count as night, resulting in continuous daylight.
• "Always below the twilight angle": meaning the Sun never rises above the twilight threshold, resulting in continuous night for that 24-hour cycle.

If the Sun follows a normal rise and set cycle, sun_status will simply be shown "-".

• moon_status: This represents the current visibility status of the Moon relative to the horizon. In some locations and on certain dates, the Moon can remain above the horizon for the entire day (never setting) or stay below the horizon for a full 24-hour cycle (never rising). In such cases, the moonrise and moonset values will be shown as "-:-", and moon_status will display either:
• "Always above the horizon": meaning the Moon will be visible in the sky throughout the 24-hour cycle.
• "Always below the horizon": meaning the Moon will not rise above the horizon during that period.

If the Moon follows a normal rise and set cycle, moon_status will simply show "-".

Practical use cases

Our Astronomy API supports a wide range of real-world applications across various industries and daily life. Here are some use cases of these discussed.

• Home Automation and IoT: Astronomical data can serve as precise triggers for smart-home events. For instance, lights can automatically turn on at sunset, coffee machines can start brewing at sunrise, or sprinklers can run just before dawn, all aligned with the natural solar cycle.
• Agriculture and Event Planning: In agriculture, knowing the exact sunrise, sunset, or moonlight conditions is essential, especially if automation needs to be implemented. Farmers can schedule field work around daylight hours, while organizers can time outdoor festivals or activities to coincide with moonlit evenings.
• Solar Energy: Solar panel tracking systems rely on precise sun azimuth and sun altitude values to maximize efficiency. Our API helps with solar farm planning, daily energy forecasting, and real-time tracking of sunlight conditions.
• Photography and Outdoor Recreation: Photographers depend on golden hour and blue hour data to capture ideal lighting conditions. Outdoor enthusiasts, hikers, and travel apps can use daylight insights to suggest safe and optimal activity times.
• Astronomy and Stargazing: Moonrise, moonset, and moon phase details allow astronomers, educators, and hobbyists to plan celestial observations, eclipse viewings, and stargazing sessions.
• Transportation and Safety: Airlines, shipping companies, and logistics planners can use daylight and twilight times to enhance scheduling, safety, and navigation.
• Wellness and Lifestyle Apps: Apps focused on health and circadian rhythms can leverage daylight data to recommend sleep schedules, meditation times, or outdoor exposure for better overall well-being.

What makes the Astronomy API especially powerful is its integration with IP Geolocation data. Instead of requiring manual entry of latitude and longitude, developers can simply provide an IP address (or use the client’s IP address) to instantly retrieve accurate, location-specific astronomical data.

Furthermore, technical documentation of the API is available on the product page of Astronomy API. Explore and integrate the Astronomy API now and bring precise Sun and Moon data into your applications with just a few lines of code.