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:
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:
You can pass the address of a location as query parameters to get the astronomical information. Here is a curl example:
# Get astronomical information for address 'New York, US'
$ curl --location --request GET 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&location=New%20York,%20US'
{
"location": {
"country": "United States of America",
"state": "New York",
"city": "",
"latitude": 41.3558443,
"longitude": -74.00776718841271
},
"date": "2020-12-21",
"current_time": "06:54:35.901",
"sunrise": "07:18",
"sunset": "16:30",
"sun_status": "-",
"solar_noon": "11:54",
"day_length": "09:12",
"sun_altitude": -4.811160884765326,
"sun_distance": 1.4717185206455985E8,
"sun_azimuth": 117.23599031322385,
"moonrise": "12:12",
"moonset": "23:58",
"moon_status": "-",
"moon_altitude": -52.075439497726244,
"moon_distance": 398627.6792531222,
"moon_azimuth": 29.97617258900459,
"moon_parallactic_angle": -26.12246297084847
}
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.
You can pass the latitude and longitude of a location as query parameters to get the astronomical information. Here is a curl example:
# Get astronomical information for -27.4748, 153.017 coordinates
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&lat=-27.4748&long=153.017'
{
"location": {
"latitude": -27.4748,
"longitude": 153.017
},
"date": "2020-12-21",
"current_time": "21:55:42.198",
"sunrise": "04:49",
"sunset": "18:42",
"sun_status": "-",
"solar_noon": "11:46",
"day_length": "13:53",
"sun_altitude": -32.52181803389665,
"sun_distance": 1.4717185206455985E8,
"sun_azimuth": 210.3191424893586,
"moonrise": "10:56",
"moonset": "23:51",
"moon_status": "-",
"moon_altitude": 25.112485813391366,
"moon_distance": 398630.7670989189,
"moon_azimuth": 275.28650130894704,
"moon_parallactic_angle": 122.50665265321304
}
You can pass any IPv4 or IPv6 address as a query parameter to get the astronomical information. Here is a curl example:
# Get astronomical information for an IP address '1.1.1.1'
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&ip=1.1.1.1'
{
"location": {
"country": "United States of America",
"state": "New York",
"city": "",
"latitude": 41.3558443,
"longitude": -74.00776718841271
},
"date": "2020-12-21",
"current_time": "06:54:35.901",
"sunrise": "07:18",
"sunset": "16:30",
"sun_status": "-",
"solar_noon": "11:54",
"day_length": "09:12",
"sun_altitude": -4.811160884765326,
"sun_distance": 1.4717185206455985E8,
"sun_azimuth": 117.23599031322385,
"moonrise": "12:12",
"moonset": "23:58",
"moon_status": "-",
"moon_altitude": -52.075439497726244,
"moon_distance": 398627.6792531222,
"moon_azimuth": 29.97617258900459,
"moon_parallactic_angle": -26.12246297084847
}
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.
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 a curl example:
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY'
Note: In above example, we used API Key everywhere. Astronomy API can be called from client side JavaScript with Request Origin authentication as well on paid plans.
The astronomy information lookup using an IP address can include geolocation information the following languages:
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:
# Get astronomical information for an IPv4 IP Address = 1.1.1.1 in Chinese language
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&ip=1.1.1.1&lang=cn'
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.
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 the curl example calls:
# Get astronomical information for -27.4748, 153.017 coordinates
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&lat=-27.4748&long=153.017&date=2018-01-01'
# Get astronomical information for an IP address
$ curl 'https://api.ipgeolocation.io/astronomy?apiKey=API_KEY&ip=1.1.1.1&date=2018-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.
sun_status is equal to "-" if the sunrise and sunset values are not equal to "-:-". sun_status can be equal to "Always above the twilight angle" or "Always below the twilight angle" if the sun is always up or always set within the current 24 hours of the day.
moon_status is equal to "-" if the moonrise and moonset values are not equal to "-:-". moon_status can be equal to "Always above the horizon" or "Always below the horizon" if the moon is always up or always set within the current 24 hours of the day.