Astronomy API Client Side Plugin
Overview
Get sunrise, sunset, moonrise, moonset, moon phases with precise twilight period times in combination with location information. One can get the astronomy information from any IP address, geo-coordinates, or street address right in your web application. It is recommended to use the request origin feature (available only in paid plans) to ensure your API key is not exposed publicly. You can add your request origin (your website domain) by logging into your account at IPGeolocation.io.
Requirements
- Internet Connection
- API Key from IPGeolocation.io
How to Get Your API Key
- Sign up here: https://app.ipgeolocation.io/signup
- (optional) Verify your email, if you signed up using email.
- Log in to your account: https://app.ipgeolocation.io/login
- After logging in, navigate to your Dashboard to find your API key: https://app.ipgeolocation.io/dashboard
Installation
To access this service, add the following Javascript call (usually within head block of your pages).
<script language="JavaScript" src="https://static.ipgeolocation.io/astronomy-api-plugin.js" type="text/javascript"></script>Note
This service will only work when embedded in web pages - no server-side calls will work.
Plugin Configurations
To instantiate the AstronomyAPI, you can use the following configuration options:
-
apiKey (optional: string): API key used for request authentication. This field is mandatory unless you have added your request origin in the dashboard, in which case it becomes optional. -
ipAddress (optional: string): Specify an IP address for which you want the astronomical information. If not provided, the client’s IP address is used by default. -
location (optional: string): Specify the location for which you want the astronomical information. -
Coordinates (optional: string): Specify the location coordinates for which you want the astronomical information. -
date (optional: string): Specify the date for which you want the astronomical information. You can pass this along with other parameters (ipAddress, location, coordinates) -
lang (optional: boolean): Language of the response. Default is en. Supported languages include: ru, de, ja, fr, cn, es, cs, it, fa, ko. -
saveToSessionStorage (optional: boolean): Saves geolocation data to session storage for temporary use.
Tip
For detailed documentation for the Astronomy API, please visit https://ipgeolocation.io/astronomy-api.html#documentation-overview.
Code Examples
1.Get Astronomical Information for a specific location
<script>
(async () => {
const astronomyAPI = new AstronomyAPI({
apiKey: "YOUR_API_KEY",
location: "New York, US"
});
const resp = await astronomyAPI.getAstronomy();
if (!resp.error_message) {
console.log(resp);
} else {
console.log("Something went wrong while fetching data", resp);
}
})();
</script>Sample Response:
Response
1{
2 "location": {
3 "location_string": "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}If there is some error while fetching the response from the API, following response will be returned, so handle it accordingly:
Response
1{
2 "error_status": "error_status_code",
3 "error_message": "error_message"
4}2.Get Astronomical Information for Location Coordinates
<script>
(async () => {
const astronomyAPI = new AstronomyAPI({
apiKey: "YOUR_API_KEY",
lat: -27.4748,
long: 153.017,
});
const resp = await astronomyAPI.getAstronomy();
if (!resp.error_message) {
console.log(resp);
} else {
console.log("Something went wrong while fetching data", resp);
}
})();
</script>Sample Response:
Response
1{
2 "location": {
3 "latitude": "-27.47480",
4 "longitude": "153.01700",
5 "country_name": "Australia",
6 "state_prov": "Queensland",
7 "city": "South Brisbane",
8 "locality": "South Brisbane",
9 "elevation": ""
10 },
11 "astronomy": {
12 "date": "2025-12-05",
13 "current_time": "00:48:29.414",
14 "mid_night": "23:38",
15 "night_end": "03:13",
16 "morning": {
17 "astronomical_twilight_begin": "03:13",
18 "astronomical_twilight_end": "03:47",
19 "nautical_twilight_begin": "03:47",
20 "nautical_twilight_end": "04:18",
21 "civil_twilight_begin": "04:18",
22 "civil_twilight_end": "04:44",
23 "blue_hour_begin": "04:08",
24 "blue_hour_end": "04:28",
25 "golden_hour_begin": "04:28",
26 "golden_hour_end": "05:18"
27 },
28 "sunrise": "04:44",
29 "sunset": "18:32",
30 "evening": {
31 "golden_hour_begin": "17:58",
32 "golden_hour_end": "18:48",
33 "blue_hour_begin": "18:48",
34 "blue_hour_end": "19:09",
35 "civil_twilight_begin": "18:32",
36 "civil_twilight_end": "18:58",
37 "nautical_twilight_begin": "18:58",
38 "nautical_twilight_end": "19:30",
39 "astronomical_twilight_begin": "19:30",
40 "astronomical_twilight_end": "20:03"
41 },
42 "night_begin": "20:03",
43 "sun_status": "-",
44 "solar_noon": "11:38",
45 "day_length": "13:47",
46 "sun_altitude": -37.39827596244138,
47 "sun_distance": 147449905.5742523,
48 "sun_azimuth": 159.44581819516998,
49 "moon_phase": "FULL_MOON",
50 "moonrise": "19:06",
51 "moonset": "04:20",
52 "moon_status": "-",
53 "moon_altitude": 31.398400021514547,
54 "moon_distance": 357494.20244737004,
55 "moon_azimuth": 334.9275491792954,
56 "moon_parallactic_angle": 155.16199342731318,
57 "moon_illumination_percentage": "99.81",
58 "moon_angle": 174.9439622483671
59 }
60}3.Get Astronomical Information for an IP Address
<script>
(async () => {
const astronomyAPI = new AstronomyAPI({
apiKey: "YOUR_API_KEY",
ip: "8.8.8.8"
});
const resp = await astronomyAPI.getAstronomy();
if (!resp.error_message) {
console.log(resp);
} else {
console.log("Something went wrong while fetching data", resp);
}
})();
</script>Sample Response:
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}4.Get Astronomical Information for a Specific Date
<script>
(async () => {
const astronomyAPI = new AstronomyAPI({
apiKey: "YOUR_API_KEY",
location: "New York, US"
date: "2024-11-04"
});
const resp = await astronomyAPI.getAstronomy();
if (!resp.error_message) {
console.log(resp);
} else {
console.log("Something went wrong while fetching data", resp);
}
})();
</script>Sample Response:
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": "2026-01-01",
14 "current_time": "10:21:09.529",
15 "mid_night": "23:59",
16 "night_end": "05:41",
17 "morning": {
18 "astronomical_twilight_begin": "05:41",
19 "astronomical_twilight_end": "06:15",
20 "nautical_twilight_begin": "06:15",
21 "nautical_twilight_end": "06:49",
22 "civil_twilight_begin": "06:49",
23 "civil_twilight_end": "07:19",
24 "blue_hour_begin": "06:37",
25 "blue_hour_end": "07:01",
26 "golden_hour_begin": "07:01",
27 "golden_hour_end": "08:03"
28 },
29 "sunrise": "07:19",
30 "sunset": "16:40",
31 "evening": {
32 "golden_hour_begin": "15:55",
33 "golden_hour_end": "16:58",
34 "blue_hour_begin": "16:58",
35 "blue_hour_end": "17:21",
36 "civil_twilight_begin": "16:40",
37 "civil_twilight_end": "17:10",
38 "nautical_twilight_begin": "17:10",
39 "nautical_twilight_end": "17:44",
40 "astronomical_twilight_begin": "17:44",
41 "astronomical_twilight_end": "18:17"
42 },
43 "night_begin": "18:17",
44 "sun_status": "-",
45 "solar_noon": "11:59",
46 "day_length": "09:20",
47 "sun_altitude": 22.285602788421738,
48 "sun_distance": 147102938.88036564,
49 "sun_azimuth": 155.50096343869086,
50 "moon_phase": "WAXING_GIBBOUS",
51 "moonrise": "14:31",
52 "moonset": "05:42",
53 "moon_status": "-",
54 "moon_altitude": -21.431610505859357,
55 "moon_distance": 360835.8162008277,
56 "moon_azimuth": 2.859017413960146,
57 "moon_parallactic_angle": -2.4464836911657195,
58 "moon_illumination_percentage": "95.35",
59 "moon_angle": 155.1019848933602
60 }
61}Error Handling
Inspect the status field in the response to detect any errors. A missing status field typically indicates a successful request, while its presence signals an issue. For example, if you are trying to fetch the data for a location that does not exist, you will get the following error response:
<script>
(async () => {
const astronomyAPI = new AstronomyAPI({
apiKey: "YOUR_API_KEY",
lat: -127.4748,
long: 53.017,
date: "2024-11-04"
});
const resp = await astronomyAPI.getAstronomy();
if (!resp.error_message) {
console.log(resp);
} else {
console.log("Something went wrong while fetching data", resp);
}
})();
</script>Sample Response:
Response
1{
2 "error_message": "'latitude' (-127.4748) or 'longitude' (53.017) is not valid. 'latitude' must be between -90.0 and +90.0 and 'longitude' must be between -180.0 and +180.0.",
3 "error_status": 400
4}