Astronomy API Documentation

Q: What data does the Astronomy API provide?

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.

Q: How can I retrieve sunrise and sunset times using the API?

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.

Q: Does the API offer information on moon phases and illumination percentages?

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.

Q: Can I obtain the sun's azimuth and altitude for a specific location and date?

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.

Q: How do I use an IP address to get astronomical data for its location?

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.

Q: Is it possible to get astronomical data for a past or future date?

Yes! The Astronomy API allows you to retrieve sun and moon data for historical dates as well as future dates.

Q: What is the format of the API response, and what information does it include?

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.

Q: Are there code examples available for integrating the Astronomy API into my project?

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.

Q: How accurate are sunrise and sunset APIs compared to traditional methods?

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.

Q: What are the usage limits or rate limits for the Astronomy API?

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.

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: In below examples, we used API Key everywhere. Astronomy API can be called from client side JavaScript with Request Origin authentication as well on only paid plans.

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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

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  },
11  "astronomy": {
12    "date": "2025-04-24",
13    "current_time": "05:51:22.144",
14    "sunrise": "06:03",
15    "sunset": "19:45",
16    "sun_status": "-",
17    "solar_noon": "12:54",
18    "day_length": "13:42",
19    "sun_altitude": -3.0152536025828494,
20    "sun_distance": 150347202.36135986,
21    "sun_azimuth": 69.93188786672897,
22    "moonrise": "04:18",
23    "moonset": "16:07",
24    "moon_status": "-",
25    "moon_altitude": 16.78325682627405,
26    "moon_distance": 365570.33476424805,
27    "moon_azimuth": 113.77523077715728,
28    "moon_parallactic_angle": -44.181547442478056,
29    "moon_phase": "WANING_CRESCENT",
30    "moon_illumination_percentage": "-16.26",
31    "moon_angle": 312.4309152252624
32  }
33}

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.

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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

Response

1{
2  "location": {
3    "latitude": "-27.47480",
4    "longitude": "153.01700"
5  },
6  "astronomy": {
7    "date": "2025-04-24",
8    "current_time": "20:09:43.894",
9    "sunrise": "06:09",
10    "sunset": "17:22",
11    "sun_status": "-",
12    "solar_noon": "11:45",
13    "day_length": "11:13",
14    "sun_altitude": -37.65833389225631,
15    "sun_distance": 150347202.36135986,
16    "sun_azimuth": 265.3769249305037,
17    "moonrise": "01:52",
18    "moonset": "14:55",
19    "moon_status": "-",
20    "moon_altitude": -55.15253040725513,
21    "moon_distance": 365506.13858637254,
22    "moon_azimuth": 198.19587897138103,
23    "moon_parallactic_angle": 163.8276392254988,
24    "moon_phase": "WANING_CRESCENT",
25    "moon_illumination_percentage": "-16.15",
26    "moon_angle": 312.60236927414405
27  }
28}

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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421"
18  },
19  "astronomy": {
20    "date": "2025-04-24",
21    "current_time": "03:11:49.137",
22    "sunrise": "06:21",
23    "sunset": "19:52",
24    "sun_status": "-",
25    "solar_noon": "13:06",
26    "day_length": "13:31",
27    "sun_altitude": -31.60250693222838,
28    "sun_distance": 150347202.36135986,
29    "sun_azimuth": 36.50375780575871,
30    "moonrise": "04:32",
31    "moonset": "16:30",
32    "moon_status": "-",
33    "moon_altitude": -15.426423427760831,
34    "moon_distance": 365498.85191422235,
35    "moon_azimuth": 85.59169056829211,
36    "moon_parallactic_angle": -52.75408030634809,
37    "moon_phase": "WANING_CRESCENT",
38    "moon_illumination_percentage": "-16.14",
39    "moon_angle": 312.62186391379714
40  }
41}

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.

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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

Note:In above examples, we used API Key everywhere. Astronomy API can be called from client side JavaScript with Request Origin authentication as well on paid plans.

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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/v2/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.

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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl '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

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl '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

Field	Type	Description	Can be empty?
ip	string	The IP address used for the astronomy lookup. Returned when queried using the `ip=` parameter or with no parameters.	Yes

• `location` json object reference

Field	Type	Description	Can be empty?
location_string	string	Location is the string, you provided for searching.	Yes
continent_code	string	2-letter code of the continent.	Yes
continent_name	string	Name of the continent.	Yes
country_code2	string	Country code (ISO 3166-1 alpha-2) of the country.	Yes
country_code3	string	Country code (ISO 3166-1 alpha-3) of the country.	Yes
country_name	string	Name of the country.	Yes
country_name_official	string	Formal name of the country.	Yes
is_eu	boolean	Is the country belong to European Union?	Yes
state_prov	string	Name of the state/province/region.	Yes
state_code	string	Code of the state/province/region.	Yes
district	string	Name of the district or county.	Yes
city	string	Name of the city.	Yes
locality	string	Smaller area, part or region of a city.	Yes
zipcode	string	ZIP/Postal code of the place.	Yes
latitude	float	Latitude of the place.	No
longitude	float	Longitude of the place.	No

• `astronomy` json object fields reference

Field	Type	Description	Can be empty?
date	string	Provided or current date in the format 'yyyy-MM-dd'.	No
current_time	string	Current time of the extracted location in the format 'HH:mm:ss.SSS'.	No
sunrise	string	Time at which sun rises at the extracted location in the format 'HH:mm'.	No
sunset	string	Time at which sun sets at the extracted location in the format 'HH:mm'.	No
sun_status*	string	Represents the sun rise and sun set status.	No
solar_noon	string	The time of day when the sun is at its highest point in the sky, in the format 'HH:mm'.	No
day_length	string	The total length of daylight for the current day in format 'HH:mm', representing the time from sunrise to sunset.	No
sun_altitude	float	The sun's altitude angle above the horizon at`current_time`, measured in degrees.	No
sun_distance	float	The distance from Earth to the sun at`current_time`, in kilometers.	No
sun_azimuth	float	The azimuth angle of the sun at`current_time`, indicating its compass direction in degrees.	No
moonrise	string	Time at which moon rises at the extracted location in the format 'HH:mm'.	No
moonset	string	Time at which moon sets at the extracted location in the format 'HH:mm'.	No
moon_status*	string	Represents the moon rise and moon set status.	No
moon_altitude	float	The moon's altitude angle above the horizon at`current_time`, measured in degrees.	No
moon_distance	float	The distance from Earth to the moon at`current_time`, in kilometers.	No
moon_azimuth	float	The azimuth angle of the moon at`current_time`, indicating its compass direction in degrees.	No
moon_parallactic_angle	float	The angle between the celestial pole and the moon's position relative to the location, measured in degrees.	No
moon_phase	string	The current phase of the moon (e.g., "WAXING_CRESCENT"), indicating its position in the lunar cycle.	No
moon_illumination_percentage	string	The percentage of the moon's surface that is illuminated by sunlight, as viewed from Earth.	No
moon_angle	float	The angular diameter of the moon as observed from Earth, measured in degrees.	No

sun_status - Indicates the current state of the sun relative to the horizon. If both the sunrise andsunsetvalues are not equal to "-:-", sun_statuswill 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 themoonriseand moonsetvalues are not equal to "-:-",moon_statuswill 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.

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 Status	Description
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.
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:

Astronomy API FAQs

What data does the Astronomy API provide?

How can I retrieve sunrise and sunset times using the API?

Does the API offer information on moon phases and illumination percentages?

Can I obtain the sun's azimuth and altitude for a specific location and date?

How do I use an IP address to get astronomical data for its location?

Is it possible to get astronomical data for a past or future date?

What is the format of the API response, and what information does it include?

Are there code examples available for integrating the Astronomy API into my project?

How accurate are sunrise and sunset APIs compared to traditional methods?

What are the usage limits or rate limits for the Astronomy API?

API for Sunset, Sunrise, Moonset and Moonrise timings

Comprehensive Sun and Moon Data

Response

Getting Astronomical Information from a Location Coordinates

Request

Response

Getting Astronomical Information from an IPv4 or IPv6 Address

Request

Response

Use Cases

Photography

Sports

Travelers

Astronomy

Solar panel placement...?

Ready to get started?Get Started with Astronomy API Today

API Documents

Database Docs

Astronomy API Documentation

Astronomy API

Getting Astronomical Information for an Address

Response

Getting Astronomical Information for Location Coordinates

Response

Getting Astronomical Information for an IPv4 or IPv6 Address

Response

Using Client or Machine IP Address

Response in Multiple Languages

Getting Astronomical Information for a Specific Date

What's New in `/v2/astronomy`

Reference to Astronomy API Response

• Standalone fields reference

• `location` json object reference

• `astronomy` json object fields reference

Error Codes

API SDKs

Astronomy API FAQs

Table of Contents

API for Sunset, Sunrise, Moonset and Moonrise timings

Comprehensive Sun and Moon Data

Response

Getting Astronomical Information from a Location Coordinates

Request

Response

Getting Astronomical Information from an IPv4 or IPv6 Address

Request

Response

Use Cases

Photography

Sports

Travelers

Astronomy

Solar panel placement...?

Ready to get started?Get Started with Astronomy API Today

API Documents

Database Docs

Astronomy API Documentation

Astronomy API

Getting Astronomical Information for an Address

Response

Getting Astronomical Information for Location Coordinates

Response

Getting Astronomical Information for an IPv4 or IPv6 Address

Response

Using Client or Machine IP Address

Response in Multiple Languages

Getting Astronomical Information for a Specific Date

What's New in /v2/astronomy

Reference to Astronomy API Response

• Standalone fields reference

• location json object reference

• astronomy json object fields reference

Error Codes

API SDKs

Astronomy API FAQs

Table of Contents

What's New in `/v2/astronomy`

• `location` json object reference

• `astronomy` json object fields reference