CTRL+K
Retrieve sunrise and sunset times, the current position of the moon, and other related information by specifying a location address, coordinates, or IP address. If no parameters are provided, the API will use the client IP address. You can also specify a date to get astronomical data for any specific day.
There are three ways to consume astronomy API:
When requesting information using an IP address with the astronomy API, you can also specify an additional "lang" parameter to receive geolocation information in multiple languages.
Get precise sunrise and sunset times, current position and distance of the sun and moon, azimuth of sun and moon and other astronomy data for any location.
Use address, location coordinates, or IP address to fetch astronomical information, making it versatile and user-friendly.
Get accurate astronomical data with an accuracy of around one minute, suitable for applications like sunrise/sunset timers.
Retrieve detailed astronomical data for any date in the past and get accurate predictions for future astronomical events.
Specify any timezone to receive astronomical data calculated according to your preferred time zone, making it easy to integrate globally.
Incorporate elevation into your queries to enhance the accuracy of sunrise, sunset, and twilight calculations for high-altitude locations.
$ pip install requests
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
| location | No | String | - | Extract astronomy information using location (preferably city) |
| lat | No | Float | - | Latitude to extract astronomy information using location coordinates |
| long | No | Float | - | Longitude to extract astronomy information using location coordinates |
| ip | No | String | request ip | IPv4 or IPv6 address to extract astronomy information using IP address |
| lang | No | String | en | Response language of "location" field in case of lookup through IP address only. Possible values are: (1) en (English) (2) de (German) (3) ru (Russian) (4) ja (Japanese) (5) fr (French) (6) cn (Chinese Simplifed) (7) es (Spanish) (8) cs (Czech) (9) it (Italian) |
| date | No | String | - | Specific date (format YYYY-MM-DD) for which astronomy data is required |
| elevation | No | Float | 0 | Elevation above sea level at the location, in meters. The value should be between 0 meter and a maximum value of 10,000 meters. Negative value is set to 0. |
| time_zone | No | String | - | Time zone to receive all time-based data in your preferred local time. |
For a comprehensive view of the API response structure and detailed field descriptions, explore the interactive Response Table by clicking here.
| HTTP Status | Reasons |
|---|---|
| 400 | (1) When provided location Address could not be geocoded
(2) When provided ip is not found in the database
(3) When date format is not correct
(4) When latitude and longitude are not valid |
Pass the address using location query parameter to get the astronomical information.
# Get astronomical information for address 'New York, US'# Response { "location": { "location_string": "new york,New York, US", "country_name": "United States", "state_prov": "New York", "city": "New York", "locality": "Clinton", "latitude": "40.76473", "longitude": "-74.00084", "elevation": "9" }, "astronomy": { "date": "2025-08-06", "current_time": "04:03:37.659", "mid_night": "01:02", "night_end": "04:09", "morning": { "astronomical_twilight_begin": "04:09", "astronomical_twilight_end": "04:50", "nautical_twilight_begin": "04:50", "nautical_twilight_end": "05:27", "civil_twilight_begin": "05:27", "civil_twilight_end": "05:57", "blue_hour_begin": "05:15", "blue_hour_end": "05:39", "golden_hour_begin": "05:39", "golden_hour_end": "06:36" }, "sunrise": "05:57", "sunset": "20:06", "evening": { "golden_hour_begin": "19:27", "golden_hour_end": "20:23", "blue_hour_begin": "20:23", "blue_hour_end": "20:47", "civil_twilight_begin": "20:06", "civil_twilight_end": "20:35", "nautical_twilight_begin": "20:35", "nautical_twilight_end": "21:12", "astronomical_twilight_begin": "21:12", "astronomical_twilight_end": "21:52" }, "night_begin": "21:52", "sun_status": "-", "solar_noon": "13:01", "day_length": "14:08", "sun_altitude": -18.85001014751317, "sun_distance": 151765334.54452804, "sun_azimuth": 46.1663368599589, "moon_phase": "WAXING_GIBBOUS", "moonrise": "18:48", "moonset": "02:38", "moon_status": "-", "moon_altitude": -13.181912288976507, "moon_distance": 393253.604156052, "moon_azimuth": 244.10081380457763, "moon_parallactic_angle": 50.56690518856842, "moon_illumination_percentage": "90.30", "moon_angle": 143.70019251110975 } }$ curl -X 'GET' 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&location=New%20York,%20US'
Pass the latitude and longitude of a location as query parameters lat and long to get the astronomical information.
# Get astronomical information for address 'New York, US'# Response { "location": { "latitude": "40.71200", "longitude": "-74.00600", "country_name": "United States", "state_prov": "New York", "city": "New York", "locality": "Financial District", "elevation": "6" }, "astronomy": { "date": "2025-08-06", "current_time": "04:04:23.522", "mid_night": "01:02", "night_end": "04:10", "morning": { "astronomical_twilight_begin": "04:10", "astronomical_twilight_end": "04:50", "nautical_twilight_begin": "04:50", "nautical_twilight_end": "05:27", "civil_twilight_begin": "05:27", "civil_twilight_end": "05:57", "blue_hour_begin": "05:15", "blue_hour_end": "05:39", "golden_hour_begin": "05:39", "golden_hour_end": "06:36" }, "sunrise": "05:57", "sunset": "20:05", "evening": { "golden_hour_begin": "19:27", "golden_hour_end": "20:23", "blue_hour_begin": "20:23", "blue_hour_end": "20:47", "civil_twilight_begin": "20:05", "civil_twilight_end": "20:35", "nautical_twilight_begin": "20:35", "nautical_twilight_end": "21:12", "astronomical_twilight_begin": "21:12", "astronomical_twilight_end": "21:52" }, "night_begin": "21:52", "sun_status": "-", "solar_noon": "13:01", "day_length": "14:08", "sun_altitude": -18.784819024484214, "sun_distance": 151765334.54452807, "sun_azimuth": 46.33395999604511, "moon_phase": "WAXING_GIBBOUS", "moonrise": "18:48", "moonset": "02:38", "moon_status": "-", "moon_altitude": -13.280527337717585, "moon_distance": 393251.31303562754, "moon_azimuth": 244.19299873353634, "moon_parallactic_angle": 50.67627072849638, "moon_illumination_percentage": "90.30", "moon_angle": 143.70638879873655 } }$ curl -X 'GET' 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&lat=40.712&long=-74.006'
Pass any IPv4 or IPv6 address as the ip query parameter to get the astronomical information.
# Get astronomical information for an IP address '1.1.1.1'# Response { "location": { "location_string": "new york", "country_name": "United States", "state_prov": "New York", "city": "New York", "locality": "", "latitude": "40.71273", "longitude": "-74.00602", "elevation": "6" }, "astronomy": { "date": "2025-08-06", "current_time": "04:04:59.463", "mid_night": "01:02", "night_end": "04:10", "morning": { "astronomical_twilight_begin": "04:10", "astronomical_twilight_end": "04:50", "nautical_twilight_begin": "04:50", "nautical_twilight_end": "05:27", "civil_twilight_begin": "05:27", "civil_twilight_end": "05:57", "blue_hour_begin": "05:15", "blue_hour_end": "05:39", "golden_hour_begin": "05:39", "golden_hour_end": "06:36" }, "sunrise": "05:57", "sunset": "20:05", "evening": { "golden_hour_begin": "19:27", "golden_hour_end": "20:23", "blue_hour_begin": "20:23", "blue_hour_end": "20:47", "civil_twilight_begin": "20:05", "civil_twilight_end": "20:35", "nautical_twilight_begin": "20:35", "nautical_twilight_end": "21:12", "astronomical_twilight_begin": "21:12", "astronomical_twilight_end": "21:52" }, "night_begin": "21:52", "sun_status": "-", "solar_noon": "13:01", "day_length": "14:08", "sun_altitude": -18.702215772647552, "sun_distance": 151765334.54452798, "sun_azimuth": 46.45809177113347, "moon_phase": "WAXING_GIBBOUS", "moonrise": "18:48", "moonset": "02:38", "moon_status": "-", "moon_altitude": -13.37900351939292, "moon_distance": 393249.5175100612, "moon_azimuth": 244.27635182539376, "moon_parallactic_angle": 50.72434980333764, "moon_illumination_percentage": "90.30", "moon_angle": 143.71124463618955 } }$ curl 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&ip=1.1.1.1'
When getting astronomical information using IP address, the response will also contain geolocation information in the location field. To get the geolocation information in a specific language, provide the language code using the lang parameter. Default geolocation response is in English.
# Get astronomical information for IP = 1.1.1.1 with geolocation in SpanishThe languages supported are:$ curl 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&ip=1.1.1.1&lang=es'
Pass the date query parameter in 'YYYY-MM-DD' format to get the astronomical information for a specific date. If no date is provided the current date will be used. All the astronomy data is calculated at the current time of day at the provided location.
# Get astronomical information for date 2023-01-01 for a particular coordinate# Get astronomical information for date 2023-01-01 for an ip address$ curl 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&lat=-29.1763&long=131.121&date=2023-01-01'$ curl 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&ip=1.1.1.1&date=2023-01-01'
Call the API without passing any location, coordinates, or IP address. It will use the calling machine's IP address to return the regional astronomical information.
$ curl 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY'
To use the Astronomy API, API credits are required. Charges apply only for successful queries, defined by a 2xx status code. If a request results in a 4xx or 5xx status code, no credits will be deducted, and any credits already charged will be refunded.
For each successful request, 1 credit will be charged for astronomical data. Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.