IPGeolocation-Logo

API for Sunset, Sunrise, Moonset and Moonrise timings

Our Astronomy API provides timings for sunrise, sunset, moonrise, moonset, sun azimuth, moon azimuth, sun altitude, moon altitude, sun distance from the earth and moon distance from the earth from latitude and longitude or an IPv4 or IPv6 address for a given date.

Get Free API Access
  • object: ,

    • Comprehensive Sun and Moon Data

    The Astronomy API provides a detailed dataset about twilight timings, different sun and moon parameters for a given date and location.

    Response
    1{
2  "location": {
3    "latitude": "40.76473",
4    "longitude": "-74.00084",
5    "country_name": "United States",
6    "state_prov": "New York",
7    "city": "New York",
8    "locality": "Midtown West",
9    "elevation": "9"
10  },
11  "astronomy": {
12    "date": "2026-12-09",
13    "current_time": "07:25:35.777",
14    "mid_night": "23:48",
15    "night_end": "05:30",
16    "morning": {
17      "astronomical_twilight_begin": "05:30",
18      "astronomical_twilight_end": "06:03",
19      "nautical_twilight_begin": "06:03",
20      "nautical_twilight_end": "06:37",
21      "civil_twilight_begin": "06:37",
22      "civil_twilight_end": "07:08",
23      "blue_hour_begin": "06:26",
24      "blue_hour_end": "06:49",
25      "golden_hour_begin": "06:49",
26      "golden_hour_end": "07:51"
27    },
28    "sunrise": "07:08",
29    "sunset": "16:28",
30    "evening": {
31      "golden_hour_begin": "15:45",
32      "golden_hour_end": "16:47",
33      "blue_hour_begin": "16:47",
34      "blue_hour_end": "17:10",
35      "civil_twilight_begin": "16:28",
36      "civil_twilight_end": "16:59",
37      "nautical_twilight_begin": "16:59",
38      "nautical_twilight_end": "17:33",
39      "astronomical_twilight_begin": "17:33",
40      "astronomical_twilight_end": "18:06"
41    },
42    "night_begin": "18:06",
43    "sun_status": "-",
44    "solar_noon": "11:48",
45    "day_length": "09:20",
46    "sun_altitude": 1.9394705633583513,
47    "sun_distance": 147366924.6229829,
48    "sun_azimuth": 122.82255749721617,
49    "moon_phase": "NEW_MOON",
50    "moonrise": "07:58",
51    "moonset": "16:41",
52    "moon_status": "-",
53    "moon_altitude": -4.890702157978301,
54    "moon_distance": 404824.1088149897,
55    "moon_azimuth": 122.68808398205493,
56    "moon_parallactic_angle": -45.99383596680553,
57    "moon_illumination_percentage": "0.21",
58    "moon_angle": 5.258133787788791
59  }
60}

    Getting Astronomical Information from a Location Coordinates

    You can pass the latitude and longitude of a location as query parameters to get the astronomical information.

    Request
    curl 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&lat=40.76473&long=-74.00084'
    Response
    1{
2  "location": {
3    "latitude": "40.76473",
4    "longitude": "-74.00084",
5    "country_name": "United States",
6    "state_prov": "New York",
7    "city": "New York",
8    "locality": "Midtown West",
9    "elevation": "9"
10  },
11  "astronomy": {
12    "date": "2025-07-17",
13    "current_time": "08:03:36.532",
14    "mid_night": "01:02",
15    "night_end": "03:40",
16    "morning": {
17      "astronomical_twilight_begin": "03:40",
18      "astronomical_twilight_end": "04:27",
19      "nautical_twilight_begin": "04:27",
20      "nautical_twilight_end": "05:07",
21      "civil_twilight_begin": "05:07",
22      "civil_twilight_end": "05:39",
23      "blue_hour_begin": "04:54",
24      "blue_hour_end": "05:20",
25      "golden_hour_begin": "05:20",
26      "golden_hour_end": "06:19"
27    },
28    "sunrise": "05:39",
29    "sunset": "20:24",
30    "evening": {
31      "golden_hour_begin": "19:44",
32      "golden_hour_end": "20:44",
33      "blue_hour_begin": "20:44",
34      "blue_hour_end": "21:09",
35      "civil_twilight_begin": "20:24",
36      "civil_twilight_end": "20:56",
37      "nautical_twilight_begin": "20:56",
38      "nautical_twilight_end": "21:37",
39      "astronomical_twilight_begin": "21:37",
40      "astronomical_twilight_end": "22:23"
41    },
42    "night_begin": "22:23",
43    "sun_status": "-",
44    "solar_noon": "13:02",
45    "day_length": "14:45",
46    "sun_altitude": 24.957683470850487,
47    "sun_distance": 152059278.3394745,
48    "sun_azimuth": 82.93803947255543,
49    "moon_phase": "LAST_QUARTER",
50    "moonrise": "-:-",
51    "moonset": "13:04",
52    "moon_status": "-",
53    "moon_altitude": 50.865120808868284,
54    "moon_distance": 371690.2207058187,
55    "moon_azimuth": 224.27457358894264,
56    "moon_parallactic_angle": 32.4113797557535,
57    "moon_illumination_percentage": "-55.99",
58    "moon_angle": 263.11859022190265
59  }
60}

    Getting Astronomical Information from an IPv4 or IPv6 Address

    You can pass any IPv4 or IPv6 address as a query parameter to get the astronomical information.

    Request
    curl 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&ip=8.8.8.8'
    Response
    1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "is_eu": false,
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "R3C 3Z5",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "locality": "Charleston Terrace",
19    "elevation": "3"
20  },
21  "astronomy": {
22    "date": "2025-07-17",
23    "current_time": "05:18:39.638",
24    "mid_night": "01:14",
25    "night_end": "04:13",
26    "morning": {
27      "astronomical_twilight_begin": "04:13",
28      "astronomical_twilight_end": "04:54",
29      "nautical_twilight_begin": "04:54",
30      "nautical_twilight_end": "05:31",
31      "civil_twilight_begin": "05:31",
32      "civil_twilight_end": "06:01",
33      "blue_hour_begin": "05:19",
34      "blue_hour_end": "05:43",
35      "golden_hour_begin": "05:43",
36      "golden_hour_end": "06:39"
37    },
38    "sunrise": "06:01",
39    "sunset": "20:27",
40    "evening": {
41      "golden_hour_begin": "19:49",
42      "golden_hour_end": "20:45",
43      "blue_hour_begin": "20:45",
44      "blue_hour_end": "21:09",
45      "civil_twilight_begin": "20:27",
46      "civil_twilight_end": "20:57",
47      "nautical_twilight_begin": "20:57",
48      "nautical_twilight_end": "21:34",
49      "astronomical_twilight_begin": "21:34",
50      "astronomical_twilight_end": "22:15"
51    },
52    "night_begin": "22:15",
53    "sun_status": "-",
54    "solar_noon": "13:14",
55    "day_length": "14:26",
56    "sun_altitude": -8.065470874567971,
57    "sun_distance": 152059278.33947453,
58    "sun_azimuth": 55.51866495593282,
59    "moon_phase": "LAST_QUARTER",
60    "moonrise": "-:-",
61    "moonset": "13:21",
62    "moon_status": "-",
63    "moon_altitude": 57.75697897229163,
64    "moon_distance": 371670.433117456,
65    "moon_azimuth": 145.37574157276907,
66    "moon_parallactic_angle": -27.227697843907947,
67    "moon_illumination_percentage": "-55.87",
68    "moon_angle": 263.25532237911756
69  }
70}

    Use Cases

    Photography

    With every sunrise and sunset, nature creates a masterpiece. Take advantage of them and plan your photography sessions ahead of time for the perfect capture with our sunrise-sunset API.

    Photography image

    Sports

    Planning a game of golf? Make sure you plan your tee for the right light. Because you know what they say,"The most important shot is the first one."

    Sports image

    Travelers

    Plan the perfect sunset romantic dinner, hiking trip or star-gazing party by taking advantage of the best star API you can find.

    For travelers

    Astronomy

    "Twilight is the time of the day when the sky looks like it has been painted by a graffiti artist". Use our astronomy API to plan the perfect time to view this breath-taking phenomenon and explore one of the most over-whelming covers of the heavens.

    astronomy use case

    Solar panel placement...?

    Trying to figure out the optimal angle for your solar panels? Use our API to get the exact solar azimuth and calculate the best solar panel angle by street address.

    Solar panel placement image

    Ready to get started?Get Started with Astronomy API Today

    Get Started
    CTA Illustration
    Documentation

    Included in

    Advance PlanSecurity PlanStandard PlanFree Plan

    Astronomy API

    The Astronomy API provides the location-based rise and set times for the Sun and Moon along with the current position, distance from earth, and azimuth of the Sun and the Moon for a specific date at the queried time.

    The Astronomy calculations are much more complex than producing an accurate result from obscure formulas throwing in a few numbers. There is always a tradeoff between the accuracy and computing time. Our Astronomy API focuses more on producing an acceptable results and has an accuracy of around one minute that is good enough for applications like sunrise/sunset timers but is not sufficient for astronomical purposes.

    There are three ways to consume the Astronomy API:

    • Using any Location Address (preferrably, city address)
    • Using Geo Coordinates (latitude & longitude)
    • Using any IPv4 or IPv6 address

    The three variations of Astronomy API take the different input sources to produce astronomical information along with location details. Here is how to consume each variation:

    Note
    For client-side calls to the endpoints mentioned below using the Request Origin (available on paid plans only), the apiKey parameter can be omitted.

    Getting Astronomical Information for an Address

    You can pass the address of a location as query parameters location to get the astronomical information. Here is an example to get the astronomical information for address 'New York, US':

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&location=New%20York%2C%20US&elevation=10'
    Response
    1{
2  "location": {
3    "location_string": "New York, US",
4    "country_name": "United States",
5    "state_prov": "New York",
6    "city": "New York",
7    "locality": "Clinton",
8    "latitude": "40.76473",
9    "longitude": "-74.00084",
10    "elevation": "9"
11  },
12  "astronomy": {
13    "date": "2025-07-17",
14    "current_time": "09:10:58.985",
15    "mid_night": "01:02",
16    "night_end": "03:40",
17    "morning": {
18      "astronomical_twilight_begin": "03:40",
19      "astronomical_twilight_end": "04:27",
20      "nautical_twilight_begin": "04:27",
21      "nautical_twilight_end": "05:07",
22      "civil_twilight_begin": "05:07",
23      "civil_twilight_end": "05:38",
24      "blue_hour_begin": "04:54",
25      "blue_hour_end": "05:20",
26      "golden_hour_begin": "05:20",
27      "golden_hour_end": "06:19"
28    },
29    "sunrise": "05:38",
30    "sunset": "20:25",
31    "evening": {
32      "golden_hour_begin": "19:44",
33      "golden_hour_end": "20:44",
34      "blue_hour_begin": "20:44",
35      "blue_hour_end": "21:09",
36      "civil_twilight_begin": "20:25",
37      "civil_twilight_end": "20:56",
38      "nautical_twilight_begin": "20:56",
39      "nautical_twilight_end": "21:37",
40      "astronomical_twilight_begin": "21:37",
41      "astronomical_twilight_end": "22:23"
42    },
43    "night_begin": "22:23",
44    "sun_status": "-",
45    "solar_noon": "13:02",
46    "day_length": "14:46",
47    "sun_altitude": 37.684583665337136,
48    "sun_distance": 152059278.33947453,
49    "sun_azimuth": 93.76489195520992,
50    "moon_phase": "LAST_QUARTER",
51    "moonrise": "-:-",
52    "moonset": "13:04",
53    "moon_status": "-",
54    "moon_altitude": 41.1571204832521,
55    "moon_distance": 371602.01272168546,
56    "moon_azimuth": 242.83522002195667,
57    "moon_parallactic_angle": 43.133797802809234,
58    "moon_illumination_percentage": "-55.46",
59    "moon_angle": 263.73075577837375
60  }
61}
    Note

    Location details like country name, state/province name, and city are provided in the response for the provided location that can be used for multiple purposes.

    elevation is an optional parameter of type double, with a default value of 0 meter and a maximum value of 10,000 meters. Negative value is set to 0.

    Getting Astronomical Information for Location Coordinates

    You can pass the latitude and longitude of a location as query parameters lat and long to get the astronomical information. Here is an example to get the astronomical information for '-27.4748, 153.017' coordinates:

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&lat=40.76473&long=-74.00084&elevation=10'
    Response
    1{
2  "location": {
3    "latitude": "40.76473",
4    "longitude": "-74.00084",
5    "country_name": "United States",
6    "state_prov": "New York",
7    "city": "New York",
8    "locality": "Midtown West",
9    "elevation": "9"
10  },
11  "astronomy": {
12    "date": "2025-07-17",
13    "current_time": "09:25:24.976",
14    "mid_night": "01:02",
15    "night_end": "03:40",
16    "morning": {
17      "astronomical_twilight_begin": "03:40",
18      "astronomical_twilight_end": "04:27",
19      "nautical_twilight_begin": "04:27",
20      "nautical_twilight_end": "05:07",
21      "civil_twilight_begin": "05:07",
22      "civil_twilight_end": "05:38",
23      "blue_hour_begin": "04:54",
24      "blue_hour_end": "05:20",
25      "golden_hour_begin": "05:20",
26      "golden_hour_end": "06:19"
27    },
28    "sunrise": "05:38",
29    "sunset": "20:25",
30    "evening": {
31      "golden_hour_begin": "19:44",
32      "golden_hour_end": "20:44",
33      "blue_hour_begin": "20:44",
34      "blue_hour_end": "21:09",
35      "civil_twilight_begin": "20:25",
36      "civil_twilight_end": "20:56",
37      "nautical_twilight_begin": "20:56",
38      "nautical_twilight_end": "21:37",
39      "astronomical_twilight_begin": "21:37",
40      "astronomical_twilight_end": "22:23"
41    },
42    "night_begin": "22:23",
43    "sun_status": "-",
44    "solar_noon": "13:02",
45    "day_length": "14:46",
46    "sun_altitude": 40.40556745814887,
47    "sun_distance": 152059278.33947453,
48    "sun_azimuth": 96.31786706454017,
49    "moon_phase": "LAST_QUARTER",
50    "moonrise": "-:-",
51    "moonset": "13:04",
52    "moon_status": "-",
53    "moon_altitude": 38.81892898270342,
54    "moon_distance": 371583.23898603366,
55    "moon_azimuth": 246.127223965273,
56    "moon_parallactic_angle": 44.656760778604536,
57    "moon_illumination_percentage": "-55.35",
58    "moon_angle": 263.8619397916658
59  }
60}

    Getting Astronomical Information for an IPv4 or IPv6 Address

    You can pass any IPv4 or IPv6 address as a query parameter ip to get the astronomical information. Here is an example to get the astronomical information for the IP address '8.8.8.8':

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&ip=8.8.8.8'
    Response
    1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "is_eu": false,
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "locality": "Charleston Terrace",
19    "elevation": "3"
20  },
21  "astronomy": {
22    "date": "2025-07-18",
23    "current_time": "03:06:31.046",
24    "mid_night": "01:14",
25    "night_end": "04:14",
26    "morning": {
27      "astronomical_twilight_begin": "04:14",
28      "astronomical_twilight_end": "04:54",
29      "nautical_twilight_begin": "04:54",
30      "nautical_twilight_end": "05:32",
31      "civil_twilight_begin": "05:32",
32      "civil_twilight_end": "06:01",
33      "blue_hour_begin": "05:20",
34      "blue_hour_end": "05:43",
35      "golden_hour_begin": "05:43",
36      "golden_hour_end": "06:39"
37    },
38    "sunrise": "06:01",
39    "sunset": "20:27",
40    "evening": {
41      "golden_hour_begin": "19:49",
42      "golden_hour_end": "20:45",
43      "blue_hour_begin": "20:45",
44      "blue_hour_end": "21:09",
45      "civil_twilight_begin": "20:27",
46      "civil_twilight_end": "20:56",
47      "nautical_twilight_begin": "20:56",
48      "nautical_twilight_end": "21:34",
49      "astronomical_twilight_begin": "21:34",
50      "astronomical_twilight_end": "22:14"
51    },
52    "night_begin": "22:14",
53    "sun_status": "-",
54    "solar_noon": "13:14",
55    "day_length": "14:25",
56    "sun_altitude": -25.97691496384962,
57    "sun_distance": 152051279.32455352,
58    "sun_azimuth": 29.157153500526988,
59    "moon_phase": "LAST_QUARTER",
60    "moonrise": "00:23",
61    "moonset": "14:34",
62    "moon_status": "-",
63    "moon_altitude": 31.341933591493504,
64    "moon_distance": 370142.7870275993,
65    "moon_azimuth": 94.69006597321885,
66    "moon_parallactic_angle": -55.06382574132873,
67    "moon_illumination_percentage": "-45.47",
68    "moon_angle": 275.1982227377768
69  }
70}
    Note

    When you get the astronomical information through an IP address, API will also return the extra fields about place information along with the astronomical information.

    Getting Astronomical Information for the required Time Zone

    The API's default behavior is to return all dates based on the time zone of the provided location. To analyze dates according to your desired time zone, use the time_zone parameter as follows:

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&lat=40.76473&long=-74.00084&time_zone=Europe%2FLondon'
    Response
    1{
2  "location": {
3    "latitude": "40.76473",
4    "longitude": "-74.00084",
5    "country_name": "United States",
6    "state_prov": "New York",
7    "city": "New York",
8    "locality": "Midtown West",
9    "elevation": "9"
10  },
11  "astronomy": {
12    "time_zone": "Europe/London",
13    "date": "2025-07-17",
14    "current_time": "15:44:42.074",
15    "mid_night": "2025-07-17 06:02",
16    "night_end": "2025-07-17 08:40",
17    "morning": {
18      "astronomical_twilight_begin": "2025-07-17 08:40",
19      "astronomical_twilight_end": "2025-07-17 09:27",
20      "nautical_twilight_begin": "2025-07-17 09:27",
21      "nautical_twilight_end": "2025-07-17 10:07",
22      "civil_twilight_begin": "2025-07-17 10:07",
23      "civil_twilight_end": "2025-07-17 10:39",
24      "blue_hour_begin": "2025-07-17 09:54",
25      "blue_hour_end": "2025-07-17 10:20",
26      "golden_hour_begin": "2025-07-17 10:20",
27      "golden_hour_end": "2025-07-17 11:19"
28    },
29    "sunrise": "2025-07-17 10:39",
30    "sunset": "2025-07-18 01:25",
31    "evening": {
32      "golden_hour_begin": "2025-07-18 00:44",
33      "golden_hour_end": "2025-07-18 01:44",
34      "blue_hour_begin": "2025-07-18 01:44",
35      "blue_hour_end": "2025-07-18 02:09",
36      "civil_twilight_begin": "2025-07-18 01:25",
37      "civil_twilight_end": "2025-07-18 01:56",
38      "nautical_twilight_begin": "2025-07-18 01:56",
39      "nautical_twilight_end": "2025-07-18 02:37",
40      "astronomical_twilight_begin": "2025-07-18 02:37",
41      "astronomical_twilight_end": "2025-07-18 03:23"
42    },
43    "night_begin": "2025-07-18 03:23",
44    "sun_status": "-",
45    "solar_noon": "2025-07-17 18:02",
46    "day_length": "14:46",
47    "sun_altitude": 54.88652737781637,
48    "sun_distance": 152059278.33947453,
49    "sun_azimuth": 113.61353349876049,
50    "moon_phase": "LAST_QUARTER",
51    "moonrise": "-:-",
52    "moonset": "2025-07-17 18:04",
53    "moon_status": "-",
54    "moon_altitude": 25.142018876738202,
55    "moon_distance": 371480.8881612358,
56    "moon_azimuth": 261.5480830860141,
57    "moon_parallactic_angle": 49.55994680103275,
58    "moon_illumination_percentage": "-54.72",
59    "moon_angle": 264.58283761108015
60  }
61}

    Time Series Lookup

    You can look up astronomy details for any location by providing a starting and ending date for the time series. The API allows a maximum 90-day lookup period, whether for future or past dates. Here's how you can do it.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy/timeSeries?apiKey=API_KEY&dateStart=2025-06-16&dateEnd=2025-06-18&lat=40.76473&long=-74.00084'
    Response
    1{
2  "location": {
3    "latitude": "40.76473",
4    "longitude": "-74.00084",
5    "country_name": "United States",
6    "state_prov": "New York",
7    "city": "New York",
8    "locality": "Midtown West",
9    "elevation": "9"
10  },
11  "astronomy": [
12    {
13      "date": "2025-06-16",
14      "mid_night": "00:56",
15      "night_end": "03:18",
16      "morning": {
17       "astronomical_twilight_begin": "03:18",
18       "astronomical_twilight_end": "04:08",
19       "nautical_twilight_begin": "04:08",
20       "nautical_twilight_end": "04:50",
21       "civil_twilight_begin": "04:50",
22       "civil_twilight_end": "05:23",
23       "blue_hour_begin": "04:37",
24       "blue_hour_end": "05:04",
25       "golden_hour_begin": "05:04",
26       "golden_hour_end": "06:05"
27     },
28     "sunrise": "05:23",
29     "sunset": "20:30",
30     "evening": {
31       "golden_hour_begin": "19:48",
32       "golden_hour_end": "20:49",
33       "blue_hour_begin": "20:49",
34       "blue_hour_end": "21:16",
35       "civil_twilight_begin": "20:30",
36       "civil_twilight_end": "21:03",
37       "nautical_twilight_begin": "21:03",
38       "nautical_twilight_end": "21:45",
39       "astronomical_twilight_begin": "21:45",
40       "astronomical_twilight_end": "22:36"
41     },
42     "night_begin": "22:36",
43     "sun_status": "-",
44     "solar_noon": "12:56",
45     "day_length": "15:06",
46     "moon_phase": "WANING_GIBBOUS",
47     "moonrise": "-:-",
48     "moonset": "10:28",
49     "moon_status": "-"
50   },
51   {
52     "date": "2025-06-17",
53     "mid_night": "00:56",
54     "night_end": "03:17",
55     "morning": {
56       "astronomical_twilight_begin": "03:17",
57       "astronomical_twilight_end": "04:08",
58       "nautical_twilight_begin": "04:08",
59       "nautical_twilight_end": "04:50",
60       "civil_twilight_begin": "04:50",
61       "civil_twilight_end": "05:23",
62       "blue_hour_begin": "04:37",
63       "blue_hour_end": "05:04",
64       "golden_hour_begin": "05:04",
65       "golden_hour_end": "06:05"
66     },
67     "sunrise": "05:23",
68     "sunset": "20:30",
69     "evening": {
70       "golden_hour_begin": "19:48",
71       "golden_hour_end": "20:50",
72       "blue_hour_begin": "20:50",
73       "blue_hour_end": "21:17",
74       "civil_twilight_begin": "20:30",
75       "civil_twilight_end": "21:03",
76       "nautical_twilight_begin": "21:03",
77       "nautical_twilight_end": "21:46",
78       "astronomical_twilight_begin": "21:46",
79       "astronomical_twilight_end": "22:36"
80     },
81     "night_begin": "22:36",
82     "sun_status": "-",
83     "solar_noon": "12:57",
84     "day_length": "15:06",
85     "moon_phase": "LAST_QUARTER",
86     "moonrise": "00:23",
87     "moonset": "11:38",
88     "moon_status": "-"
89   },
90   {
91     "date": "2025-06-18",
92     "mid_night": "00:57",
93     "night_end": "03:18",
94     "morning": {
95       "astronomical_twilight_begin": "03:18",
96       "astronomical_twilight_end": "04:08",
97       "nautical_twilight_begin": "04:08",
98       "nautical_twilight_end": "04:51",
99       "civil_twilight_begin": "04:51",
100       "civil_twilight_end": "05:23",
101       "blue_hour_begin": "04:37",
102       "blue_hour_end": "05:04",
103       "golden_hour_begin": "05:04",
104       "golden_hour_end": "06:05"
105     },
106     "sunrise": "05:23",
107     "sunset": "20:31",
108     "evening": {
109       "golden_hour_begin": "19:49",
110       "golden_hour_end": "20:50",
111       "blue_hour_begin": "20:50",
112       "blue_hour_end": "21:17",
113       "civil_twilight_begin": "20:31",
114       "civil_twilight_end": "21:03",
115       "nautical_twilight_begin": "21:03",
116       "nautical_twilight_end": "21:46",
117       "astronomical_twilight_begin": "21:46",
118       "astronomical_twilight_end": "22:37"
119     },
120     "night_begin": "22:37",
121     "sun_status": "-",
122     "solar_noon": "12:57",
123     "day_length": "15:07",
124     "moon_phase": "LAST_QUARTER",
125     "moonrise": "00:46",
126     "moonset": "12:49",
127     "moon_status": "-"
128   }
129  ]
130}
    Note

    All other parameters are the same as for a single-date lookup.

    Using Client or Machine IP Address

    You can call the astronomy API without passing any coordinates or IP address as well. It will use the calling machine's IP address to return the regional astronomical information. Here is an example:

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY'
    Note

    Astronomy details are calculated based on the following rules:

    • Parameters considered: latitude & longitude, location, and IP.
    • If all parameters are provided, latitude & longitude are preferred.
    • Between location and IP, location is preferred.
    • If no parameters are provided, the client’s IP address is used.

    Response in Multiple Languages

    The astronomy information lookup using an IP address can include geolocation information in the following languages:

    • English (en)
    • German (de)
    • Russian (ru)
    • Japanese (ja)
    • French (fr)
    • Chinese Simplified (cn)
    • Spanish (es)
    • Czech (cs)
    • Italian (it)
    • Korean (ko)
    • Persian (fa)
    • Portuguese (pt)

    By default, the API responds in English. But you can change the response language by passing the language code as a query parameter lang. Here is an example:

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&ip=1.1.1.1&lang=cn'
    Note
    Only the paid plan subscriptions can get the response in languages other than English. All the other subscriptions will only get the response in English.

    Getting Astronomical Information for a Specific Date

    Along with the above two variations, there is a third variation that you can get the astronomical information for a specific date. You can pass date query parameter with the date value. Here are some example calls for coordinates search along with date:

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&lat=-27.4748&long=153.017&date=2025-01-01'

    Alternatively, you can also call this endpoint with ip address and date parameters:

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/astronomy?apiKey=API_KEY&ip=1.1.1.1&date=2025-01-01'
    Note
    Date must be in 'YYYY-MM-DD' format. No other format will be accepted and by default, current date will be used. All the astronomical information is calculated at the current time of day at the provided location.

    What's New in /v2/astronomy

    Below are the key updates introduced in the /v2/astronomy API endpoint compared to the previous /astronomy version:

    • All astronomy-related data is now grouped under a single astronomy object, making the response more consistent with our overall API structure.
    • When calling /v2/astronomy without any parameters or with ip=, the response now includes an ip field to indicate the IP address used for the lookup.
    • When the location= parameter is used, the location object now follows the same field naming conventions as in IP-based queries for consistency across responses:
      • location.location → location.location_string
      • location.country → location.country_name
      • location.state → location.state_prov

    Reference to Astronomy API Response

    Below we have provided separate tables for location object and astronomy object fields that can be returned by Astronomy API.

    • Standalone fields reference

    FieldTypeDescriptionCan be empty?
    ipstring

    The IP address used for the astronomy lookup. Returned when queried using the ip= parameter or with no parameters.

    		Yes

    • location json object reference

    FieldTypeDescriptionCan be empty?
    location_stringstring

    Location is the string, you provided for searching.

    		Yes
    continent_codestring

    2-letter code of the continent.

    		Yes
    continent_namestring

    Name of the continent.

    		Yes
    country_code2string

    Country code (ISO 3166-1 alpha-2) of the country.

    		Yes
    country_code3string

    Country code (ISO 3166-1 alpha-3) of the country.

    		Yes
    country_namestring

    Name of the country.

    		Yes
    country_name_officialstring

    Formal name of the country.

    		Yes
    is_euboolean

    Is the country belong to European Union?

    		Yes
    state_provstring

    Name of the state/province/region.

    		Yes
    state_codestring

    Code of the state/province/region.

    		Yes
    districtstring

    Name of the district or county.

    		Yes
    citystring

    Name of the city.

    		Yes
    localitystring

    Smaller area, part or region of a city.

    		Yes
    zipcodestring

    ZIP/Postal code of the place.

    		Yes
    latitudefloat

    Latitude of the place.

    		No
    longitudefloat

    Longitude of the place.

    		No
    elevationstring

    Elevation above sea level at the location, in meters.

    		Yes

    • astronomy json object reference

    FieldTypeDescriptionCan be empty?
    time_zonestring

    Appears (with the provided value) only when the user includes a time_zone in the query to specify which time to observe.

    		No
    datestring

    Provided or current date in the format yyyy-MM-dd.

    		No
    current_timestring

    Current time of the extracted location in the format HH:mm:ss.SSS.

    		No
    mid_nightstring

    Astronomical midnight (nadir) for the given date.

    		No
    night_endstring

    End of night / start of astronomical twilight (morning).

    		No
    night_beginstring

    Start of night / end of astronomical twilight (evening).

    		No
    sunrisestring

    Time at which sun rises at the extracted location in the format HH:mm.

    		No
    sunsetstring

    Time at which sun sets at the extracted location in the format HH:mm.

    		No
    sun_statusstring

    Represents the sun rise and sun set status.

    		No
    solar_noonstring

    The time of day when the sun is at its highest point in the sky, in the format HH:mm.

    		No
    day_lengthstring

    The total length of daylight for the current day in format HH:mm, representing the time from sunrise to sunset.

    		No
    sun_altitudefloat

    The sun's altitude angle above the horizon at current_time, measured in degrees.

    		No
    sun_distancefloat

    The distance from Earth to the sun at current_time, in kilometers.

    		No
    sun_azimuthfloat

    The azimuth angle of the sun at current_time, indicating its compass direction in degrees.

    		No
    moonrisestring

    Time at which moon rises at the extracted location in the format HH:mm.

    		No
    moonsetstring

    Time at which moon sets at the extracted location in the format HH:mm.

    		No
    moon_statusstring

    Represents the moon rise and moon set status.

    		No
    moon_altitudefloat

    The moon's altitude angle above the horizon at current_time, measured in degrees.

    		No
    moon_distancefloat

    The distance from Earth to the moon at current_time, in kilometers.

    		No
    moon_azimuthfloat

    The azimuth angle of the moon at current_time, indicating its compass direction in degrees.

    		No
    moon_parallactic_anglefloat

    The angle between the celestial pole and the moon's position relative to the location, measured in degrees.

    		No
    moon_phasestring

    The current phase of the moon (e.g., WAXING_CRESCENT), indicating its position in the lunar cycle.

    		No
    moon_illumination_percentagestring

    The percentage of the moon's surface that is illuminated by sunlight, as viewed from Earth.

    		No
    moon_anglefloat

    The angular diameter of the moon as observed from Earth, measured in degrees.

    		No
    morning.astronomical_twilight_beginstring

    Start of astronomical twilight (pre‑dawn) in the morning.

    		No
    morning.astronomical_twilight_endstring

    End of astronomical twilight in the morning.

    		No
    morning.nautical_twilight_beginstring

    Start of nautical twilight (when the horizon first becomes visible) in the morning.

    		No
    morning.nautical_twilight_endstring

    End of nautical twilight in the morning.

    		No
    morning.civil_twilight_beginstring

    Start of civil twilight (enough light for outdoor activities) in the morning.

    		No
    morning.civil_twilight_endstring

    End of civil twilight in the morning.

    		No
    morning.blue_hour_beginstring

    Start of blue hour (soft, diffused light) before sunrise.

    		No
    morning.blue_hour_endstring

    End of blue hour before sunrise.

    		No
    morning.golden_hour_beginstring

    Start of golden hour (warm, low‑angle light) before sunrise.

    		No
    morning.golden_hour_endstring

    End of golden hour before sunrise.

    		No
    evening.golden_hour_beginstring

    Start of golden hour (warm, low‑angle light) after sunset.

    		No
    evening.golden_hour_endstring

    End of golden hour after sunset.

    		No
    evening.blue_hour_beginstring

    Start of blue hour (soft, diffused light) after sunset.

    		No
    evening.blue_hour_endstring

    End of blue hour after sunset.

    		No
    evening.civil_twilight_beginstring

    Start of civil twilight (enough light for outdoor activities) in the evening.

    		No
    evening.civil_twilight_endstring

    End of civil twilight in the evening.

    		No
    evening.nautical_twilight_beginstring

    Start of nautical twilight (horizon still visible) in the evening.

    		No
    evening.nautical_twilight_endstring

    End of nautical twilight in the evening.

    		No
    evening.astronomical_twilight_beginstring

    Start of astronomical twilight (night sky begins) in the evening.

    		No
    evening.astronomical_twilight_endstring

    End of astronomical twilight in the evening.

    		No

    sun_status: - Indicates the current state of the sun relative to the horizon. If both the sunrise and sunset values are not equal to "-:-", sun_status will be set to "-", indicating no special status. If the sun is continuously above the twilight angle, sun_status may be set to "Always above the twilight angle", indicating perpetual daylight. Conversely, if the sun remains below the twilight angle, the status may read "Always below the twilight angle", indicating that the sun does not rise within the current 24-hour period.

    moon_status: - Represents the current state of the moon in relation to the horizon. If both the moonrise and moonset values are not equal to "-:-", moon_status will be set to "-", indicating no special status. If the moon is always visible above the horizon, moon_status may be assigned "Always above the horizon", signifying that the moon does not set within the current 24-hour period. Conversely, if the moon is consistently below the horizon, it may read "Always below the horizon", indicating it does not rise during this timeframe.

    Note
    All timestamp fields (excluding current_time and duration day_length) are formatted as yyyy-MM-dd HH:mm when a time_zone is provided; otherwise they use HH:mm.

    Error Codes

    Astronomy API returns HTTP status code 200 for a successful API request along with the response.

    While, in case of a bad or invalid request, Astronomy API returns 4xx HTTP status code along with a descriptive message explaining the reason for the error.

    Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions:

    HTTP StatusDescription
    400
    Bad Request

    It is returned for one of the following reasons:

    • If the provided location address is invalid or not found.

    • If special character(s) ( ) [ ] { } | ^ ` is passed in the API URL either as paramter or its value. Specially in case of API key.

    • If the provided date is not in the format 'yyyy-MM-dd'.

    • If the provided IP address does not found in our database.

    • Thrown when the provided elevation exceeds the maximum allowed value (10,000 meters / 10 km).

    • Thrown when the span between the start and end dates is greater than 90 days.

    • Thrown when the provided time_zone is invalid or unrecognized.

    401
    Unauthorized

    It is returned for one of the following reasons:

    • If API key (as apiKey URL parameter) is missing from the request to IP Geolocation API.

    • If an invalid (a random value) API key is provided.

    • If the API request is made from an unverified ipgeolocation.io account.

    • If your account has been disabled or locked to use by the admin due to abuse or illegal activity.

    • When the request to IP Geolocation API is made using API key for a database subscription

    • When the request to IP Geolocation API is made on the 'paused' subscription.

    • If you’re making API requests after your subscription trial has been expired.

    • If your active until date has passed and you need to upgrade your account.

    405
    Method Not Allowed

    • If wrong HTTP request method is used for calling the endpoint. Only GET method is allowed for /astronomy  endpoint requests.

    429
    Too Many Requests

    It is returned for one of the following reasons:

    • If the API usage limit has reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'.

    • If the surcharge API usage limit has reached against the subscribed plan.

    499
    Client Closed Request

    • If the client has set the very short request or connection timeout, leading to the server closing the request prematurely.

    5XX
    Server Side Error

    • If a 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), 504 (Gateway Timeout), or 505 (HTTP Version Not Supported) status code is returned, it indicates an issue on our end. Please contact us with your request at support@ipgeolocation.io for further assistance.

    API SDKs

    To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.

    Our SDKs are also available on Github. Feel free to help us improve them. Following are the available SDKs:

    Frequently Asked Questions

    The IP Geolocation Astronomy API provides comprehensive astronomical data, including sunrise and sunset times, moonrise and moonset times, solar noon, day length, the current sun position (azimuth and altitude), moon phases, and moon illumination percentages. It also delivers data for any location on Earth based on geographic coordinates or IP address.
    Yes! The Astronomy API includes detailed moon data, such as the current moon phase (e.g., WAXING_CRESCENT, NEW_MOON, FULL_MOON), and the moon’s illumination percentage. This data is perfect for astronomy apps, weather forecasting, photography planning, and tide tracking.
    The Astronomy API integrates seamlessly with IP Geolocation’s database. By simply providing an IP address in your API request, the system automatically determines the geographic coordinates and returns accurate astronomical data, including sunrise, sunset, sun position, and moon phases for that IP address location.
    The Astronomy API returns data in JSON (default) and XML formats, making it easy to integrate into web and mobile applications. The response includes sunrise and sunset times, solar noon, day length, sun position (azimuth and altitude), moonrise and moonset times, moon phase, and illumination percentage.
    The Astronomy API delivers highly accurate sunrise and sunset times by using advanced astronomical algorithms and precise geolocation data. Its accuracy is comparable to traditional methods, such as astronomical almanacs and observatory data, making it reliable for professional applications like scientific research, solar energy planning, and outdoor event scheduling.
    You can retrieve accurate sunrise and sunset times by sending a simple request to the Astronomy API with your preferred location parameters—latitude and longitude, city name, or IP address. Optionally, include a date parameter to get data for a past or future date. The API returns the sunrise and sunset times in local time in JSON and XML formats for easy integration.
    Yes! The Astronomy API provides real-time sun position data, including azimuth and altitude, for any specific geographic location and date. This feature is ideal for solar panel optimization, solar tracking, and outdoor planning applications.
    Yes! The Astronomy API allows you to retrieve sun and moon data for historical dates as well as future dates.
    Yes. IP Geolocation provides comprehensive documentation with code examples in multiple programming languages, including JavaScript, Python, PHP, and even in curl format. You can find these examples in the documentation section, making it easy to integrate the Astronomy API into your application or system quickly.
    IP Geolocation offers different pricing plans with varying usage limits. The free plan includes 30, 000 requests per month, ideal for testing and small projects. Paid plans provide higher request limits, priority support, and additional features to support enterprise-level applications.