Loading
Loading
Retrieve sunrise and sunset times, the current position of the moon, and other related information by specifying a location address, coordinates, or IP address.
The Astronomy API provides precise astronomical data for any location worldwide. Get accurate sunrise and sunset times, moon phases, twilight periods, golden hour and blue hour schedules, and current sun and moon positions. Supports address lookup, GPS coordinates, IP address geolocation, and custom dates.
Pass your API key as the apiKey parameter in every request.
This is version v1.0 of the API.
The following parameters can be used in your API requests. All parameters are passed as query string parameters.
locationoptionalStringdefault: New York, USExtract astronomy information using location (preferably city)
latoptionalFloatLatitude to extract astronomy information using location coordinates
longoptionalFloatLongitude to extract astronomy information using location coordinates
ipoptionalStringIPv4 or IPv6 address to extract astronomy information using IP address
langoptionalStringdefault: enresponse language of "location" field in case of lookup through IP address only.
dateoptionalStringSpecific date (format YYYY-MM-DD) for which astronomy data is required
elevationoptionalFLoatdefault: 0Elevation 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_zoneoptionalStringdefault: Time zone to receive all time-based data in your preferred local time.
A successful request returns a 200 OK response with a JSON object containing the astronomy data. The response includes the top-level fields listed below. See the response preview on the right for the full JSON structure.
locationThe location information
astronomyThe astronomy information
The astronomy object includes the following fields:
dateThe current date
current_timeThe current time
time_zoneThe time zone of the location
mid_nightThe time of midnight (solar-based)
night_endThe time when night ends (start of astronomical twilight)
morning.astronomical_twilight_beginThe start time of astronomical twilight in the morning
morning.astronomical_twilight_endThe end time of astronomical twilight in the morning
morning.nautical_twilight_beginThe start time of nautical twilight in the morning
morning.nautical_twilight_endThe end time of nautical twilight in the morning
morning.civil_twilight_beginThe start time of civil twilight in the morning
morning.civil_twilight_endThe end time of civil twilight in the morning
morning.blue_hour_beginThe beginning of the blue hour in the morning
morning.blue_hour_endThe end of the blue hour in the morning
morning.golden_hour_beginThe beginning of the golden hour in the morning
morning.golden_hour_endThe end of the golden hour in the morning
sunriseThe time of sunrise
sunsetThe time of sunset
evening.golden_hour_beginThe beginning of the golden hour in the evening
evening.golden_hour_endThe end of the golden hour in the evening
evening.blue_hour_beginThe beginning of the blue hour in the evening
evening.blue_hour_endThe end of the blue hour in the evening
evening.civil_twilight_beginThe start of civil twilight in the evening
evening.civil_twilight_endThe end of civil twilight in the evening
evening.nautical_twilight_beginThe start of nautical twilight in the evening
evening.nautical_twilight_endThe end of nautical twilight in the evening
evening.astronomical_twilight_beginThe start of astronomical twilight in the evening
evening.astronomical_twilight_endThe end of astronomical twilight in the evening
night_beginThe time when night begins (end of astronomical twilight)
sun_statusThe current status of the sun (e.g., "rising", "setting", "-")
solar_noonThe time when the sun reaches its highest point in the sky
day_lengthThe total duration of daylight
sun_altitudeThe altitude angle of the sun above the horizon in degrees
sun_distanceThe distance from the Earth to the sun in kilometers
sun_azimuthThe azimuth angle of the sun in degrees from true north
moon_phaseThe current phase of the moon (e.g., "WAXING_GIBBOUS")
moonriseThe time of moonrise
moonsetThe time of moonset
moon_statusThe current status of the moon (e.g., "rising", "setting", "-")
moon_altitudeThe altitude angle of the moon above the horizon in degrees
moon_distanceThe distance from the Earth to the moon in kilometers
moon_azimuthThe azimuth angle of the moon in degrees from true north
moon_parallactic_angleThe parallactic angle of the moon in degrees
moon_illumination_percentageThe percentage of the moon illuminated by sunlight
moon_angleThe geometric angle of the moon relative to the observer
When a lookup is performed using GPS coordinates, the location object includes the following fields:
latitudeThe latitude of the geographical location
longitudeThe longitude of the geographical location
country_nameThe country of the geographical location
state_provThe state or province of the geographical location
cityThe city of the geographical location
localityThe locality or neighborhood of the geographical location
elevationThe elevation of the geographical location
When a lookup is performed using the 'location' parameter, the location object includes the following fields:
location_stringThe complete geographical location, including country, state, city, and locality
country_nameThe country of the geographical location
state_provThe state or province of the geographical location
cityThe city of the geographical location
localityThe locality or neighborhood of the geographical location
latitudeThe latitude of the geographical location
longitudeThe longitude of the geographical location
elevationThe elevation of the geographical location
When a lookup is performed using the 'ip' parameter, the location object includes the following fields:
continent_codeThe code for the continent
continent_nameThe name of the continent
country_code2The 2-letter country code (ISO 3166-1 alpha-2)
country_code3The 3-letter country code (ISO 3166-1 alpha-3)
country_nameThe common name of the country
country_name_officialThe official name of the country
is_euWhether the country is part of the European Union
state_provThe state or province of the geographical location
state_codeThe code for the state or province
districtThe district of the geographical location
cityThe city of the geographical location
zipcodeThe postal code of the geographical location
latitudeThe latitude of the geographical location
longitudeThe longitude of the geographical location
localityThe locality or neighborhood of the geographical location
elevationThe elevation of the geographical location
The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.
Latitude must be between -90 and 90.
'999.999.999.999' is not an IP string literal.
You must provide date in the 'yyyy-MM-dd' format
We couldn't find the location (ZZZNOTEXIST). Try a city or state level location address only.