SearchCtrl+K

APIs/Astronomy API

Astronomy API - Location Based Astronomy Data

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:

Using address (preferably city address)
Using location coordinates (latitude and longitude)
Using an IP address

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.

Try Playground Get Free API Key

10K Free Credits, No Credit Card Required

Features

Location Based Data

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.

Multiple Input Methods

Use address, location coordinates, or IP address to fetch astronomical information, making it versatile and user-friendly.

Real-Time Calculations

Get accurate astronomical data with an accuracy of around one minute, suitable for applications like sunrise/sunset timers.

Timeless Astronomical Insights

Retrieve detailed astronomical data for any date in the past and get accurate predictions for future astronomical events.

Custom Timezone Support

Specify any timezone to receive astronomical data calculated according to your preferred time zone, making it easy to integrate globally.

Elevation-Aware Calculations

Incorporate elevation into your queries to enhance the accuracy of sunrise, sunset, and twilight calculations for high-altitude locations.

API Endpoint

GEThttps://api.apifreaks.com/v2.0/geolocation/astronomy

Test

Explore the complete API reference with detailed request parameters, response fields, error codes, and code examples visit API Reference.

LANGUAGE


$ pip install requests
import requests 

url = "https://api.apifreaks.com/v2.0/geolocation/astronomy?lat=11.2&long=11.2&lang=en&date=2024-09-01"

payload = {}
headers = {
	'X-apiKey': 'API-KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

How-To-Guides

Astronomical Information for an Address

Pass the address using location query parameter to get the astronomical information.

# Get astronomical information for address 'New York, US'
$ curl -X 'GET'   'https://api.apifreaks.com/v2.0/geolocation/astronomy?apiKey=API-KEY&location=New%20York,%20USA&elevation=10'

# Response
{
    "location": {
        "location_string": "New York, USA",
        "country_name": "United States",
        "state_prov": "New York",
        "city": "Syracuse",
        "locality": "Destiny USA Mall",
        "latitude": "43.06923",
        "longitude": "-76.17249",
        "elevation": "128"
    },
    "astronomy": {
        "date": "2026-07-08",
        "current_time": "08:18:11.806",
        "mid_night": "01:09",
        "night_end": "03:19",
        "morning": {
            "astronomical_twilight_begin": "03:19",
            "astronomical_twilight_end": "04:14",
            "nautical_twilight_begin": "04:14",
            "nautical_twilight_end": "04:58",
            "civil_twilight_begin": "04:58",
            "civil_twilight_end": "05:33",
            "blue_hour_begin": "04:44",
            "blue_hour_end": "05:12",
            "golden_hour_begin": "05:12",
            "golden_hour_end": "06:16"
        },
        "sunrise": "05:33",
        "sunset": "20:46",
        "evening": {
            "golden_hour_begin": "20:03",
            "golden_hour_end": "21:06",
            "blue_hour_begin": "21:06",
            "blue_hour_end": "21:34",
            "civil_twilight_begin": "20:46",
            "civil_twilight_end": "21:20",
            "nautical_twilight_begin": "21:20",
            "nautical_twilight_end": "22:05",
            "astronomical_twilight_begin": "22:05",
            "astronomical_twilight_end": "22:59"
        },
        "night_begin": "22:59",
        "sun_status": "-",
        "solar_noon": "13:09",
        "day_length": "15:13",
        "sun_altitude": 27.321441002051646,
        "sun_distance": 152098283.03028187,
        "sun_azimuth": 83.97186761125164,
        "moon_phase": "LAST_QUARTER",
        "moonrise": "00:26",
        "moonset": "14:37",
        "moon_status": "-",
        "moon_altitude": 58.551149269478934,
        "moon_distance": 374888.71932885225,
        "moon_azimuth": 204.80400233098723,
        "moon_parallactic_angle": 18.385564615910248,
        "moon_illumination_percentage": "-42.29",
        "moon_angle": 278.87554796203597
    }
}

Astronomical Information for Location Coordinates

Pass the latitude and longitude of a location as query parameters lat and long to get the astronomical information.

# Get astronomical information for New York coordinates
$ curl -X 'GET'   'https://api.apifreaks.com/v2.0/geolocation/astronomy?apiKey=API-KEY&lat=40.76473&long=-74.00084&elevation=10'

# Response
{
    "location": {
        "latitude": "40.76473",
        "longitude": "-74.00084",
        "country_name": "United States",
        "state_prov": "New York",
        "city": "New York",
        "locality": "Midtown West",
        "elevation": "9"
    },
    "astronomy": {
        "date": "2026-07-08",
        "current_time": "08:18:12.346",
        "mid_night": "01:01",
        "night_end": "03:29",
        "morning": {
            "astronomical_twilight_begin": "03:29",
            "astronomical_twilight_end": "04:18",
            "nautical_twilight_begin": "04:18",
            "nautical_twilight_end": "04:59",
            "civil_twilight_begin": "04:59",
            "civil_twilight_end": "05:32",
            "blue_hour_begin": "04:46",
            "blue_hour_end": "05:12",
            "golden_hour_begin": "05:12",
            "golden_hour_end": "06:13"
        },
        "sunrise": "05:32",
        "sunset": "20:30",
        "evening": {
            "golden_hour_begin": "19:48",
            "golden_hour_end": "20:49",
            "blue_hour_begin": "20:49",
            "blue_hour_end": "21:15",
            "civil_twilight_begin": "20:30",
            "civil_twilight_end": "21:02",
            "nautical_twilight_begin": "21:02",
            "nautical_twilight_end": "21:44",
            "astronomical_twilight_begin": "21:44",
            "astronomical_twilight_end": "22:32"
        },
        "night_begin": "22:32",
        "sun_status": "-",
        "solar_noon": "13:01",
        "day_length": "14:58",
        "sun_altitude": 28.691610641909943,
        "sun_distance": 152098283.0302818,
        "sun_azimuth": 84.11610567304757,
        "moon_phase": "LAST_QUARTER",
        "moonrise": "00:20",
        "moonset": "14:23",
        "moon_status": "-",
        "moon_altitude": 59.84300282799233,
        "moon_distance": 374888.68623116106,
        "moon_azimuth": 210.4529167697743,
        "moon_parallactic_angle": 23.270450972326564,
        "moon_illumination_percentage": "-42.29",
        "moon_angle": 278.8756282824625
    }
}

Astronomical Information for an IPv4 or IPv6 Address

Pass any IPv4 or IPv6 address as the ip query parameter to get the astronomical information.

# Get astronomical information for an IP address '8.8.8.8'
$ curl 'https://api.apifreaks.com/v2.0/geolocation/astronomy?apiKey=API-KEY&ip=8.8.8.8'

# Response
{
    "ip": "8.8.8.8",
    "location": {
        "continent_code": "NA",
        "continent_name": "North America",
        "country_code2": "US",
        "country_code3": "USA",
        "country_name": "United States",
        "country_name_official": "United States of America",
        "is_eu": false,
        "state_prov": "California",
        "state_code": "US-CA",
        "district": "Santa Clara",
        "city": "Mountain View",
        "zipcode": "94043-1351",
        "latitude": "37.42240",
        "longitude": "-122.08421",
        "locality": "Charleston Terrace",
        "elevation": "3"
    },
    "astronomy": {
        "date": "2026-07-08",
        "current_time": "05:18:12.938",
        "mid_night": "01:13",
        "night_end": "04:03",
        "morning": {
            "astronomical_twilight_begin": "04:03",
            "astronomical_twilight_end": "04:46",
            "nautical_twilight_begin": "04:46",
            "nautical_twilight_end": "05:24",
            "civil_twilight_begin": "05:24",
            "civil_twilight_end": "05:54",
            "blue_hour_begin": "05:12",
            "blue_hour_end": "05:36",
            "golden_hour_begin": "05:36",
            "golden_hour_end": "06:33"
        },
        "sunrise": "05:54",
        "sunset": "20:32",
        "evening": {
            "golden_hour_begin": "19:53",
            "golden_hour_end": "20:50",
            "blue_hour_begin": "20:50",
            "blue_hour_end": "21:14",
            "civil_twilight_begin": "20:32",
            "civil_twilight_end": "21:02",
            "nautical_twilight_begin": "21:02",
            "nautical_twilight_end": "21:40",
            "astronomical_twilight_begin": "21:40",
            "astronomical_twilight_end": "22:23"
        },
        "night_begin": "22:23",
        "sun_status": "-",
        "solar_noon": "13:13",
        "day_length": "14:37",
        "sun_altitude": -7.006856118127633,
        "sun_distance": 152098283.0302818,
        "sun_azimuth": 54.67981832902274,
        "moon_phase": "LAST_QUARTER",
        "moonrise": "00:41",
        "moonset": "14:38",
        "moon_status": "-",
        "moon_altitude": 52.35621467762323,
        "moon_distance": 374888.6499463031,
        "moon_azimuth": 120.28398942143878,
        "moon_parallactic_angle": -44.89505156105447,
        "moon_illumination_percentage": "-42.29",
        "moon_angle": 278.8757163374507
    }
}

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 Spanish
$ curl 'https://api.apifreaks.com/v2.0/geolocation/astronomy?apiKey=API-KEY&ip=1.1.1.1&lang=es'

The languages supported are:

en (English)
de (German)
ru (Russian)
ja (Japanese)
fr (French)
cn (Chinese Simplifed)
es (Spanish)
cs (Czech)
it (Italian)
ko (Korean)
fa (Persian)
pt (Portuguese)

Astronomical Information for a Specific Date

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
$ curl 'https://api.apifreaks.com/v2.0/geolocation/astronomy?apiKey=API-KEY&lat=-29.1763&long=131.121&date=2023-01-01'

# Get astronomical information for date 2023-01-01 for an ip address
$ curl 'https://api.apifreaks.com/v2.0/geolocation/astronomy?apiKey=API-KEY&ip=1.1.1.1&date=2023-01-01'

Astronomical Information for Calling Machine IP

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/v2.0/geolocation/astronomy?apiKey=API-KEY'

Pricing

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.

Price Estimation Calculator