Astronomy API

Overview

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.
Important
Each successful Astronomy Lookup costs 1 credits per request. The X-Credits-Charged response header shows the total credits charged for the request. For details, please refer to our Credits Usage Guide.

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/v3/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/v3/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/v3/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/v3/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/v3/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/v3/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/v3/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.

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/v3/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/v3/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.

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.

1.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

2. 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

3. 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 parameter 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 is 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.
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 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.
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.
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.
Yes! The Astronomy API allows you to retrieve sun and moon data for historical dates as well as future dates.
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.
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.
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.
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.

Subscribe Our Newsletter

Get the latest in geolocation tech, straight to your inbox.