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

How to Get Your API Key

  1. Sign up here: https://app.ipgeolocation.io/signup
  2. (optional) Verify your email, if you signed up using email.
  3. Log in to your account: https://app.ipgeolocation.io/login
  4. 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.v3.0.0.js" type="text/javascript"></script>

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.
  • lat (optional: number) : Latitude of the location. Provide together with long .
  • long (optional: number) : Longitude of the location. Provide together with lat .
  • elevation (optional: number) : Elevation of the location in meters. The maximum supported value is 10,000 meters.
  • date (optional: string) : Date for a single lookup in YYYY-MM-DD format. You can pass it with ipAddress , location , or lat and long .
  • timeZone (optional: string) : IANA time zone, such as Europe/London , used to convert returned event times.
  • dateStart (optional: string) : Start date for a time-series lookup in YYYY-MM-DD format.
  • dateEnd (optional: string) : End date for a time-series lookup in YYYY-MM-DD format. The maximum time-series range is 90 days.
  • lang (optional: string) : Language of the response. Default is en. Supported languages include: ru, de, ja, fr, cn, es, cs, it, fa, ko, pt, ar.
  • saveToSessionStorage (optional: boolean) : Caches successful responses in session storage for the current browser tab. Cache entries are specific to the lookup parameters.

Use getAstronomy() for a single-date lookup. Use getAstronomyTimeSeries() with dateStart and dateEnd for a date range.

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_status) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview
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": "2024-11-04",
14    "current_time": "08:12:44.883",
15    "mid_night": "23:39",
16    "night_end": "04:57",
17    "morning": {
18      "astronomical_twilight_begin": "04:57",
19      "astronomical_twilight_end": "05:29",
20      "nautical_twilight_begin": "05:29",
21      "nautical_twilight_end": "06:01",
22      "civil_twilight_begin": "06:01",
23      "civil_twilight_end": "06:30",
24      "blue_hour_begin": "05:51",
25      "blue_hour_end": "06:13",
26      "golden_hour_begin": "06:13",
27      "golden_hour_end": "07:10"
28    },
29    "sunrise": "06:30",
30    "sunset": "16:48",
31    "evening": {
32      "golden_hour_begin": "16:08",
33      "golden_hour_end": "17:05",
34      "blue_hour_begin": "17:05",
35      "blue_hour_end": "17:27",
36      "civil_twilight_begin": "16:48",
37      "civil_twilight_end": "17:16",
38      "nautical_twilight_begin": "17:16",
39      "nautical_twilight_end": "17:49",
40      "astronomical_twilight_begin": "17:49",
41      "astronomical_twilight_end": "18:21"
42    },
43    "night_begin": "18:21",
44    "sun_status": "-",
45    "solar_noon": "11:39",
46    "day_length": "10:18",
47    "sun_altitude": 16.025928084156632,
48    "sun_distance": 148361706.3935511,
49    "sun_azimuth": 128.14060120476182,
50    "moon_phase": "WAXING_CRESCENT",
51    "moonrise": "09:48",
52    "moonset": "18:29",
53    "moon_status": "-",
54    "moon_altitude": -14.923954777733469,
55    "moon_distance": 396332.621613144,
56    "moon_azimuth": 113.76283054867883,
57    "moon_parallactic_angle": -51.452160801531605,
58    "moon_illumination_percentage": "8.42",
59    "moon_angle": 33.74321660247666
60  }
61}

If there is some error while fetching the response from the API, following response will be returned, so handle it accordingly:

Response Preview
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_status) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview
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",
            ipAddress: "8.8.8.8"
        });

        const resp = await astronomyAPI.getAstronomy();

        if (!resp.error_status) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview
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_status) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview
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": "2024-11-04",
14    "current_time": "08:12:44.883",
15    "mid_night": "23:39",
16    "night_end": "04:57",
17    "morning": {
18      "astronomical_twilight_begin": "04:57",
19      "astronomical_twilight_end": "05:29",
20      "nautical_twilight_begin": "05:29",
21      "nautical_twilight_end": "06:01",
22      "civil_twilight_begin": "06:01",
23      "civil_twilight_end": "06:30",
24      "blue_hour_begin": "05:51",
25      "blue_hour_end": "06:13",
26      "golden_hour_begin": "06:13",
27      "golden_hour_end": "07:10"
28    },
29    "sunrise": "06:30",
30    "sunset": "16:48",
31    "evening": {
32      "golden_hour_begin": "16:08",
33      "golden_hour_end": "17:05",
34      "blue_hour_begin": "17:05",
35      "blue_hour_end": "17:27",
36      "civil_twilight_begin": "16:48",
37      "civil_twilight_end": "17:16",
38      "nautical_twilight_begin": "17:16",
39      "nautical_twilight_end": "17:49",
40      "astronomical_twilight_begin": "17:49",
41      "astronomical_twilight_end": "18:21"
42    },
43    "night_begin": "18:21",
44    "sun_status": "-",
45    "solar_noon": "11:39",
46    "day_length": "10:18",
47    "sun_altitude": 16.025928084156632,
48    "sun_distance": 148361706.3935511,
49    "sun_azimuth": 128.14060120476182,
50    "moon_phase": "WAXING_CRESCENT",
51    "moonrise": "09:48",
52    "moonset": "18:29",
53    "moon_status": "-",
54    "moon_altitude": -14.923954777733469,
55    "moon_distance": 396332.621613144,
56    "moon_azimuth": 113.76283054867883,
57    "moon_parallactic_angle": -51.452160801531605,
58    "moon_illumination_percentage": "8.42",
59    "moon_angle": 33.74321660247666
60  }
61}

5. Return Astronomical Event Times in a Specific Time Zone

The API performs the astronomical calculation for the resolved location and converts event times to the requested time zone. Converted events include a date because some events can fall on the previous or next calendar day.

<script>
    (async () => {
        const astronomyAPI = new AstronomyAPI({
            apiKey: "YOUR_API_KEY",
            ipAddress: "115.186.118.130",
            date: "2026-03-07",
            timeZone: "Europe/London"
        });

        const resp = await astronomyAPI.getAstronomy();

        if (!resp.error_status) {
            console.log(resp.astronomy.time_zone);
            console.log(resp.astronomy.sunrise);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response (excerpt):

Response Preview
1{
2  "location": {
3    "country_name": "Pakistan",
4    "state_prov": "Punjab",
5    "city": "Faisalabad",
6    "latitude": "31.45037",
7    "longitude": "73.13496",
8    "elevation": "190"
9  },
10  "astronomy": {
11    "time_zone": "Europe/London",
12    "date": "2026-03-07",
13    "sunrise": "2026-03-07 01:25",
14    "sunset": "2026-03-07 13:11",
15    "solar_noon": "2026-03-07 07:18"
16  }
17}

6. Get Astronomical Information for a Date Range

Use getAstronomyTimeSeries() to retrieve daily Sun and Moon events for up to 90 days. In a time-series response, astronomy is an array. Date-level entries do not include current-time position fields such as current_time , sun_altitude , or moon_altitude .

<script>
    (async () => {
        const astronomyAPI = new AstronomyAPI({
            apiKey: "YOUR_API_KEY",
            lat: 40.76473,
            long: -74.00084,
            dateStart: "2025-06-16",
            dateEnd: "2025-06-18"
        });

        const resp = await astronomyAPI.getAstronomyTimeSeries();

        if (!resp.error_status) {
            resp.astronomy.forEach((day) => {
                console.log(day.date, day.sunrise, day.sunset);
            });
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response (excerpt):

Response Preview
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}

Error Handling

Inspect the error_status field in the response to detect any errors. A missing error_status field typically indicates a successful request, while its presence signals an issue. HTTP errors return the API status code. Network and response parsing failures return error_status: 0 . For example, if you are trying to fetch data using invalid coordinates, 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_status) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview
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}

Subscribe to Our Newsletter

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