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, the response will also include "location" and "geo" field for geolocation information. In this scenario, you can also specify an additional "lang" parameter to receive geolocation information in multiple languages.

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.

API Endpoint

GET

https://api.apifreaks.com/v1.0/geolocation/astronomy

Test

LANGUAGE

Python

PHP

Java

Node

Ruby

$ pip install requests

API Request

Parameter	Required	Type	Default	Description
location	No	String		Extract astronomy informatin using location (preferably city)
lat	No	Integer		Latitude to extract time zone informatin using location coordinates
long	No	Integer		Longitude to extract time zone informatin using location coordinates
ip	No	String		IPv4 or IPv6 address to extract time zone informatin 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

API Response

Here are the response fields when performing a lookup using geographical coordinates (latitude and longitude):

Field	Type	Requirement	Description
date	String	Mandatory	The current date
current_time	String	Mandatory	The current time
sunrise	String	Optional	The time of sunrise
sunset	String	Optional	The time of sunset
sun_status	String	Optional	The current status of the sun (e.g., "rising", "setting")
solar_noon	String	Optional	The time of solar noon
day_length	String	Optional	The length of the day
sun_altitude	Float	Mandatory	The altitude angle of the sun above the horizon
sun_distance	Float	Mandatory	The distance from the Earth to the sun
sun_azimuth	Float	Mandatory	The azimuth angle of the sun
moonrise	String	Optional	The time of moonrise
moonset	String	Optional	The time of moonset
moon_status	String	Optional	The current status of the moon (e.g., "rising", "setting")
moon_altitude	Float	Mandatory	The altitude angle of the moon above the horizon
moon_distance	Float	Mandatory	The distance from the Earth to the moon
moon_azimuth	Float	Mandatory	The azimuth angle of the moon
moonparallacticangle	Float	Mandatory	The parallactic angle of the moon
location.latitude	Float	Mandatory	The latitude coordinate of the location
location.longitude	Float	Mandatory	The longitude coordinate of the location

When a lookup is performed using the 'location' parameter, the following additional fields are appended to the above fields:

Field	Type	Requirement	Description
location.location	String	Mandatory	The complete geographical location, including country, state, city, and locality
location.country	String	Optional	The country of the geographical location
location.state	String	Optional	The state of the geographical location
location.city	String	Optional	The city of the geographical location
location.locality	String	Optional	The locality or neighborhood of the geographical location

When no parameters or IP address are provided, the user's current location is detected. If a parameter is provided, the IP location is used. The following fields are appended to the previously mentioned fields:

Field	Type	Requirement	Description
geo.country_code2	String	Mandatory	The 2-letter country code (ISO 3166-1 alpha-2)
geo.country_code3	String	Mandatory	The 3-letter country code (ISO 3166-1 alpha-3)
geo.country_name	String	Mandatory	The common name of the country
geo.country_name_official	String	Mandatory	The official name of the country
geo.state_prov	String	Optional	The state or province of the geographical location
geo.state_code	String	Optional	The code for the state or province
geo.district	String	Optional	The district of the geographical location
geo.city	String	Optional	The city of the geographical location
geo.zip_code	String	Optional	The postal code of the geographical location

HTTP Error Codes

HTTP Status	Reasons
400	(1) When provided location Address could not be geocoded (2) When provided ip is not found in the db (3) When date format is not correct (4) When latitude and longitude are not valid

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 --location --request GET 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&location=New%20York,%20US'
# Response
{ 
  "location": {
    "country": "United States of America",
    "state": "New York", 
    "city": "",
    "latitude": 41.3558443, 
    "longitude": -74.00776718841271 
  },
  "date": "2020-12-21",
  "current_time": "06:54:35.901",
  "sunrise": "07:18",
  "sunset": "16:30", 
  "sun_status": "-", 
  "solar_noon": "11:54", 
  "day_length": "09:12",
  "sun_altitude": -4.811160884765326,
  "sun_distance": 1.4717185206455985E8,
  "sun_azimuth": 117.23599031322385,
  "moonrise": "12:12",
  "moonset": "23:58",
  "moon_status": "-",
  "moon_altitude": -52.075439497726244,
  "moon_distance": 398627.6792531222, 
  "moon_azimuth": 29.97617258900459,
  "moon_parallactic_angle": -26.12246297084847 
}

When getting astronomical information using location address, the response will contain location field with location details like country, city etc. for the provided location.

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 address 'New York, US'$ curl --location --request GET 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&location=New%20York,%20US'
# Response
{ 
  "location": {
    "country": "United States of America",
    "state": "New York", 
    "city": "",
    "latitude": 41.3558443, 
    "longitude": -74.00776718841271 
  },
  "date": "2020-12-21",
  "current_time": "06:54:35.901",
  "sunrise": "07:18",
  "sunset": "16:30", 
  "sun_status": "-", 
  "solar_noon": "11:54", 
  "day_length": "09:12",
  "sun_altitude": -4.811160884765326,
  "sun_distance": 1.4717185206455985E8,
  "sun_azimuth": 117.23599031322385,
  "moonrise": "12:12",
  "moonset": "23:58",
  "moon_status": "-",
  "moon_altitude": -52.075439497726244,
  "moon_distance": 398627.6792531222, 
  "moon_azimuth": 29.97617258900459,
  "moon_parallactic_angle": -26.12246297084847 
}

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 '1.1.1.1'$ curl 'https://api.apifreaks.com/v1.0/geolocation/astronomy?apiKey=API-KEY&ip=1.1.1.1'
# Response
{ 
  "location": {
    "country": "United States of America",
    "state": "New York", 
    "city": "",
    "latitude": 41.3558443, 
    "longitude": -74.00776718841271 
  },
  "date": "2020-12-21",
  "current_time": "06:54:35.901",
  "sunrise": "07:18",
  "sunset": "16:30", 
  "sun_status": "-", 
  "solar_noon": "11:54", 
  "day_length": "09:12",
  "sun_altitude": -4.811160884765326,
  "sun_distance": 1.4717185206455985E8,
  "sun_azimuth": 117.23599031322385,
  "moonrise": "12:12",
  "moonset": "23:58",
  "moon_status": "-",
  "moon_altitude": -52.075439497726244,
  "moon_distance": 398627.6792531222, 
  "moon_azimuth": 29.97617258900459,
  "moon_parallactic_angle": -26.12246297084847 
}

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/v1.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)

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/v1.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/v1.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/v1.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.