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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

1{
2  "location": {
3    "location": "New York, US",
4    "country": "United States",
5    "state": "New York",
6    "city": "New York",
7    "locality": "Clinton",
8    "latitude": 40.76473335,
9    "longitude": -74.00083980660943
10  },
11  "date": "2024-11-04",
12  "current_time": "08:13:22.978",
13  "sunrise": "06:30",
14  "sunset": "16:48",
15  "sun_status": "-",
16  "solar_noon": "11:39",
17  "day_length": "10:18",
18  "sun_altitude": 16.120293371563754,
19  "sun_distance": 148361706.39355108,
20  "sun_azimuth": 128.26575101712496,
21  "moonrise": "09:49",
22  "moonset": "18:29",
23  "moon_status": "-",
24  "moon_altitude": -14.81836182838389,
25  "moon_distance": 396331.25698682835,
26  "moon_azimuth": 113.85094239453929,
27  "moon_parallactic_angle": -51.40390182984849,
28  "moon_phase": "WAXING_CRESCENT",
29  "moon_illumination_percentage": "8.43",
30  "moon_angle": 33.74826084504092
31}

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

1{
2  "location": {
3    "latitude": -27.4748,
4    "longitude": 153.017
5  },
6  "date": "2024-11-04",
7  "current_time": "23:28:59.711",
8  "sunrise": "04:54",
9  "sunset": "18:08",
10  "sun_status": "-",
11  "solar_noon": "11:31",
12  "day_length": "13:14",
13  "sun_altitude": -46.89343713201794,
14  "sun_distance": 148361706.39355108,
15  "sun_azimuth": 180.89506040990295,
16  "moonrise": "06:15",
17  "moonset": "20:46",
18  "moon_status": "-",
19  "moon_altitude": -25.365567944837675,
20  "moon_distance": 396297.670873638,
21  "moon_azimuth": 214.4609302018781,
22  "moon_parallactic_angle": 145.49291581261554,
23  "moon_phase": "WAXING_CRESCENT",
24  "moon_illumination_percentage": "8.49",
25  "moon_angle": 33.87230698192152
26}

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

1{
2  "location": {
3    "continent_code": "NA",
4    "continent_name": "North America",
5    "country_code2": "US",
6    "country_code3": "USA",
7    "country_name": "United States",
8    "country_name_official": "United States of America",
9    "is_eu": false,
10    "state_prov": "California",
11    "state_code": "US-CA",
12    "district": "Santa Clara",
13    "city": "Mountain View",
14    "zipcode": "94043-1351",
15    "latitude": 37.4224,
16    "longitude": -122.08421
17  },
18  "date": "2024-11-04",
19  "current_time": "05:42:37.429",
20  "sunrise": "06:37",
21  "sunset": "17:06",
22  "sun_status": "-",
23  "solar_noon": "11:51",
24  "day_length": "10:29",
25  "sun_altitude": -11.233664962711332,
26  "sun_distance": 148361706.39355108,
27  "sun_azimuth": 101.18075504079837,
28  "moonrise": "09:56",
29  "moonset": "19:01",
30  "moon_status": "-",
31  "moon_altitude": -44.88852591210425,
32  "moon_distance": 396268.3036138962,
33  "moon_azimuth": 93.53924174509945,
34  "moon_parallactic_angle": -63.45786017771775,
35  "moon_phase": "WAXING_CRESCENT",
36  "moon_illumination_percentage": "8.54",
37  "moon_angle": 33.98061036315428
38}

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/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)
• Persian (fa)
• Korean (ko)

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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.

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

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

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.

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:

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:

• IP Geolocation API Java SDK
• IP Geolocation API C-Sharp dotNet SDK
• IP Geolocation API Typescript SDK
• IP Geolocation API PHP SDK
• IP Geolocation API JQuery SDK