--- title: Astronomy API - Location Based Astronomy Data version: 1.0.0 description: "Retrieve sunrise and sunset times, current position of the moon, and other astronomical data for any location and date. Supports lookup by city name or address (location), GPS coordinates (lat/long), an explicit IP address (ip), or the requester's own client IP when none of those are provided. Returns comprehensive astronomy data including twilight times, blue hour, golden hour, sun and moon positions, distances, azimuths, and moon phase. The location object's field set varies by lookup mode: address lookups return a location_string plus basic fields, coordinate lookups return the same basic fields without location_string, and IP-based lookups (explicit ip or client-IP fallback) return a richer geo-IP field set (continent, country codes, EU membership, state code, district, zip code) plus a top-level ip field, but never location_string. Pass time_zone to convert all time fields into a specific IANA time zone." openapi: 3.1.1 servers: - https://api.apifreaks.com/v2.0 paths: 1 operations: 1 schemas: 6 --- ## Table of Contents - [Astronomy API - Location Based Astronomy Data v1.0.0](#astronomy-api-location-based-astronomy-data-v100) - [Authentication](#authentication) - [Other APIs](#other-apis) - [getAstronomyData](#getastronomydata) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [AstronomyResponse](#astronomyresponse) - [AstronomyLocation](#astronomylocation) - [AstronomyData](#astronomydata) - [AstronomyMorning](#astronomymorning) - [AstronomyEvening](#astronomyevening) - [ErrorResponse](#errorresponse) # Astronomy API - Location Based Astronomy Data v1.0.0 Retrieve sunrise and sunset times, current position of the moon, and other astronomical data for any location and date. Supports lookup by city name or address (location), GPS coordinates (lat/long), an explicit IP address (ip), or the requester's own client IP when none of those are provided. Returns comprehensive astronomy data including twilight times, blue hour, golden hour, sun and moon positions, distances, azimuths, and moon phase. The location object's field set varies by lookup mode: address lookups return a location_string plus basic fields, coordinate lookups return the same basic fields without location_string, and IP-based lookups (explicit ip or client-IP fallback) return a richer geo-IP field set (continent, country codes, EU membership, state code, district, zip code) plus a top-level ip field, but never location_string. Pass time_zone to convert all time fields into a specific IANA time zone. Base URLs: * [https://api.apifreaks.com/v2.0](https://api.apifreaks.com/v2.0) ## Authentication * API Key (ApiKeyAuthHeader) - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header. * API Key (ApiKeyAuthQuery) - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter. ## Other APIs ### getAstronomyData `GET /geolocation/astronomy` *Returns sunrise, sunset, moon phase, and celestial positions for a given location and date.* Retrieve sunrise and sunset times, current position of the moon, and other related information by specifying a location address, location coordinates, IP address, or using the client IP address if no parameter is passed. #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |format|query|string|false|Format of the response. Can be "json" or "xml".| |location|query|string|false|Extract astronomy information using location (preferably city)| |lat|query|number(float)|false|Latitude to extract astronomy information using location coordinates| |long|query|number(float)|false|Longitude to extract astronomy information using location coordinates| |ip|query|string|false|IPv4 or IPv6 address to extract astronomy information using IP address| |lang|query|string|false|Response language of "location" field in case of lookup through IP address only.| |date|query|string(date)|false|Specific date (format YYYY-MM-DD) for which astronomy data is required| |elevation|query|number(float)|false|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|query|string|false|Time zone to receive all time-based data in your preferred local time.| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| |format|xml| |lang|en| |lang|de| |lang|ru| |lang|ja| |lang|fr| |lang|cn| |lang|es| |lang|cs| |lang|it| |lang|ko| |lang|fa| |lang|pt| > Example responses > Successful response with astronomy data ```json { "location": { "location_string": "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": "2026-07-24", "current_time": "05:39:55.740", "mid_night": "01:02", "night_end": "03:50", "morning": { "astronomical_twilight_begin": "03:50", "astronomical_twilight_end": "04:34", "nautical_twilight_begin": "04:34", "nautical_twilight_end": "05:13", "civil_twilight_begin": "05:13", "civil_twilight_end": "05:44", "blue_hour_begin": "05:00", "blue_hour_end": "05:26", "golden_hour_begin": "05:26", "golden_hour_end": "06:24" }, "sunrise": "05:44", "sunset": "20:20", "evening": { "golden_hour_begin": "19:39", "golden_hour_end": "20:38", "blue_hour_begin": "20:38", "blue_hour_end": "21:03", "civil_twilight_begin": "20:20", "civil_twilight_end": "20:50", "nautical_twilight_begin": "20:50", "nautical_twilight_end": "21:30", "astronomical_twilight_begin": "21:30", "astronomical_twilight_end": "22:14" }, "night_begin": "22:14", "sun_status": "-", "solar_noon": "13:02", "day_length": "14:35", "sun_altitude": -1.724678050716447, "sun_distance": 151988138.3404624, "sun_azimuth": 61.7231663467785, "moon_phase": "WAXING_GIBBOUS", "moonrise": "16:59", "moonset": "01:05", "moon_status": "-", "moon_altitude": -47.89342665088803, "moon_distance": 404852.80222395214, "moon_azimuth": 275.0508821352747, "moon_parallactic_angle": 57.14257561268031, "moon_illumination_percentage": "76.99", "moon_angle": 122.67519000797743 } } ``` ```json { "location": { "latitude": "40.71280", "longitude": "-74.00600", "country_name": "United States", "state_prov": "New York", "city": "New York City", "locality": "", "elevation": "6" }, "astronomy": { "date": "2026-07-24", "current_time": "05:40:09.712", "mid_night": "01:02", "night_end": "03:50", "morning": { "astronomical_twilight_begin": "03:50", "astronomical_twilight_end": "04:34", "nautical_twilight_begin": "04:34", "nautical_twilight_end": "05:14", "civil_twilight_begin": "05:14", "civil_twilight_end": "05:45", "blue_hour_begin": "05:01", "blue_hour_end": "05:26", "golden_hour_begin": "05:26", "golden_hour_end": "06:25" }, "sunrise": "05:45", "sunset": "20:19", "evening": { "golden_hour_begin": "19:39", "golden_hour_end": "20:38", "blue_hour_begin": "20:38", "blue_hour_end": "21:03", "civil_twilight_begin": "20:19", "civil_twilight_end": "20:50", "nautical_twilight_begin": "20:50", "nautical_twilight_end": "21:30", "astronomical_twilight_begin": "21:30", "astronomical_twilight_end": "22:13" }, "night_begin": "22:13", "sun_status": "-", "solar_noon": "13:02", "day_length": "14:34", "sun_altitude": -1.7138810477761148, "sun_distance": 151988138.34046236, "sun_azimuth": 61.759759720006855, "moon_phase": "WAXING_GIBBOUS", "moonrise": "16:58", "moonset": "01:05", "moon_status": "-", "moon_altitude": -47.936765082140305, "moon_distance": 404853.01478817535, "moon_azimuth": 275.0302780092609, "moon_parallactic_angle": 57.21501710401273, "moon_illumination_percentage": "77.00", "moon_angle": 122.67696159469526 } } ``` ```json { "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-24", "current_time": "02:40:09.167", "mid_night": "01:15", "night_end": "04:20", "morning": { "astronomical_twilight_begin": "04:20", "astronomical_twilight_end": "05:00", "nautical_twilight_begin": "05:00", "nautical_twilight_end": "05:36", "civil_twilight_begin": "05:36", "civil_twilight_end": "06:06", "blue_hour_begin": "05:25", "blue_hour_end": "05:48", "golden_hour_begin": "05:48", "golden_hour_end": "06:43" }, "sunrise": "06:06", "sunset": "20:23", "evening": { "golden_hour_begin": "19:45", "golden_hour_end": "20:41", "blue_hour_begin": "20:41", "blue_hour_end": "21:04", "civil_twilight_begin": "20:23", "civil_twilight_end": "20:52", "nautical_twilight_begin": "20:52", "nautical_twilight_end": "21:28", "astronomical_twilight_begin": "21:28", "astronomical_twilight_end": "22:08" }, "night_begin": "22:08", "sun_status": "-", "solar_noon": "13:14", "day_length": "14:17", "sun_altitude": -29.345451007769825, "sun_distance": 151988138.3404624, "sun_azimuth": 23.09240894097684, "moon_phase": "WAXING_GIBBOUS", "moonrise": "17:06", "moonset": "01:34", "moon_status": "-", "moon_altitude": -11.054713589548413, "moon_distance": 404853.00649734883, "moon_azimuth": 245.50238573115115, "moon_parallactic_angle": 53.576490644915204, "moon_illumination_percentage": "77.00", "moon_angle": 122.67689249117335 } } ``` > Bad Request – Invalid parameters provided ```json { "message": "Latitude must be between -90 and 90." } ``` ```json { "message": "'999.999.999.999' is not an IP string literal." } ``` ```json { "message": "You must provide date in the 'yyyy-MM-dd' format" } ``` > Not Found ```json { "message": "We couldn't find the location (ZZZNOTEXIST). Try a city or state level location address only." } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with astronomy data|[AstronomyResponse](#astronomyresponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request – Invalid parameters provided|[ErrorResponse](#errorresponse)| |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found|[ErrorResponse](#errorresponse)| #### Response Headers |Status|Header|Type|Format|Description| |---|---|---|---|---| |200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| To perform this operation, you must be authenticated by means of one of the following methods: ApiKeyAuthHeader, ApiKeyAuthQuery ## Schemas ### AstronomyResponse Astronomy data response containing location information and astronomical data. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |ip|string|false|none|IPv4 or IPv6 address used for the geo-IP lookup. Present when the ip parameter is passed explicitly, or when no location, lat/long, or ip parameter is supplied at all (the API falls back to the requesting client's IP address). Absent when location or lat/long is used.| |location|[AstronomyLocation](#astronomylocation)|false|none|Geographic location information for the astronomy calculation. The set of populated fields depends on which lookup mode the request used: (1) location param (geocode-by-address) returns location_string plus a basic field set (country_name, state_prov, city, locality, latitude, longitude, elevation); (2) lat + long params (geocode-by-coordinates) returns the same basic field set minus location_string, and locality may be an empty string when the coordinates don't resolve to a named sub-area; (3) ip param, or no location/lat/long/ip param at all (falls back to geo-IP lookup of the client's IP), returns the full geo-IP field set — continent_code, continent_name, country_code2, country_code3, country_name_official, is_eu, state_code, district, zipcode — in addition to the basic fields, but never location_string. elevation can be an empty string when elevation data is unavailable for the resolved location.| |astronomy|[AstronomyData](#astronomydata)|true|none|Complete astronomical data for the specified location and date.| ### AstronomyLocation Geographic location information for the astronomy calculation. The set of populated fields depends on which lookup mode the request used: (1) location param (geocode-by-address) returns location_string plus a basic field set (country_name, state_prov, city, locality, latitude, longitude, elevation); (2) lat + long params (geocode-by-coordinates) returns the same basic field set minus location_string, and locality may be an empty string when the coordinates don't resolve to a named sub-area; (3) ip param, or no location/lat/long/ip param at all (falls back to geo-IP lookup of the client's IP), returns the full geo-IP field set — continent_code, continent_name, country_code2, country_code3, country_name_official, is_eu, state_code, district, zipcode — in addition to the basic fields, but never location_string. elevation can be an empty string when elevation data is unavailable for the resolved location. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |location_string|string|false|none|The location query parameter echoed back as-is. Present only for geocode-by-address lookups (location param); absent for lat/long and ip-based lookups.| |continent_code|string|false|none|The two-letter code of the continent (e.g., "NA"). Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |continent_name|string|false|none|The full name of the continent (e.g., "North America"). Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |country_code2|string|false|none|The ISO 3166-1 alpha-2 two-letter country code (e.g., "US"). Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |country_code3|string|false|none|The ISO 3166-1 alpha-3 three-letter country code (e.g., "USA"). Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |country_name|string|false|none|The common name of the country (e.g., "United States"). Present in all lookup modes.| |country_name_official|string|false|none|The official full name of the country (e.g., "United States of America"). Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |is_eu|boolean|false|none|Whether the country belongs to the European Union. Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |state_prov|string|false|none|Name of the state/province/region. Present in all lookup modes.| |state_code|string|false|none|Code of the state/province/region. Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |district|string|false|none|Name of the district or county. Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |city|string|false|none|Name of the city. Present in all lookup modes.| |zipcode|string|false|none|ZIP/Postal code of the place. Geo-IP field only: present for ip param or default client-IP lookups; absent for location/lat/long geocode lookups.| |latitude|string|true|none|The geographic latitude of the location. Present in all lookup modes.| |longitude|string|true|none|The geographic longitude of the location. Present in all lookup modes.| |locality|string|false|none|Smaller area, part or region of a city. Present in all lookup modes, but may be an empty string for lat/long or geo-IP lookups when no named sub-area resolves.| |elevation|string|false|none|The elevation of the geographical location, in meters. Present in all lookup modes, but may be an empty string when elevation data is unavailable for the resolved location.| ### AstronomyData Complete astronomical data for the specified location and date. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |time_zone|string|false|none|Appears (with the provided value) only when the user includes a time_zone in the query to specify which time to observe.| |date|string|true|none|The date astronomy data was calculated for. Defaults to today's date; reflects the date query parameter's value when that parameter is supplied.| |current_time|string|true|none|The current time| |mid_night|string|true|none|The time of midnight (solar-based)| |night_end|string|true|none|The time when night ends (start of astronomical twilight)| |morning|[AstronomyMorning](#astronomymorning)|true|none|Morning astronomical data including twilight, blue hour, and golden hour times.| |sunrise|string|true|none|The time of sunrise| |sunset|string|true|none|The time of sunset| |evening|[AstronomyEvening](#astronomyevening)|true|none|Evening astronomical data including golden hour, blue hour, and twilight times.| |night_begin|string|true|none|The time when night begins (end of astronomical twilight)| |sun_status|string|true|none|The current status of the sun (e.g., "rising", "setting", "-")| |solar_noon|string|true|none|The time when the sun reaches its highest point in the sky| |day_length|string|true|none|The total duration of daylight| |sun_altitude|number(float)|true|none|The altitude angle of the sun above the horizon in degrees| |sun_distance|number(float)|true|none|The distance from the Earth to the sun in kilometers| |sun_azimuth|number(float)|true|none|The azimuth angle of the sun in degrees from true north| |moon_phase|string|true|none|The current phase of the moon (e.g., "WAXING_GIBBOUS")| |moonrise|string|true|none|The time of moonrise| |moonset|string|true|none|The time of moonset| |moon_status|string|true|none|The current status of the moon (e.g., "rising", "setting", "-")| |moon_altitude|number(float)|true|none|The altitude angle of the moon above the horizon in degrees| |moon_distance|number(float)|true|none|The distance from the Earth to the moon in kilometers| |moon_azimuth|number(float)|true|none|The azimuth angle of the moon in degrees from true north| |moon_parallactic_angle|number(float)|true|none|The parallactic angle of the moon in degrees| |moon_illumination_percentage|string|true|none|The percentage of the moon illuminated by sunlight. A negative value indicates the moon is in a waning phase.| |moon_angle|number(float)|true|none|The geometric angle of the moon relative to the observer| ### AstronomyMorning Morning astronomical data including twilight, blue hour, and golden hour times. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |astronomical_twilight_begin|string|true|none|The start time of astronomical twilight in the morning| |astronomical_twilight_end|string|true|none|The end time of astronomical twilight in the morning| |nautical_twilight_begin|string|true|none|The start time of nautical twilight in the morning| |nautical_twilight_end|string|true|none|The end time of nautical twilight in the morning| |civil_twilight_begin|string|true|none|The start time of civil twilight in the morning| |civil_twilight_end|string|true|none|The end time of civil twilight in the morning| |blue_hour_begin|string|true|none|The beginning of the blue hour in the morning| |blue_hour_end|string|true|none|The end of the blue hour in the morning| |golden_hour_begin|string|true|none|The beginning of the golden hour in the morning| |golden_hour_end|string|true|none|The end of the golden hour in the morning| ### AstronomyEvening Evening astronomical data including golden hour, blue hour, and twilight times. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |golden_hour_begin|string|true|none|The beginning of the golden hour in the evening| |golden_hour_end|string|true|none|The end of the golden hour in the evening| |blue_hour_begin|string|true|none|The beginning of the blue hour in the evening| |blue_hour_end|string|true|none|The end of the blue hour in the evening| |civil_twilight_begin|string|true|none|The start of civil twilight in the evening| |civil_twilight_end|string|true|none|The end of civil twilight in the evening| |nautical_twilight_begin|string|true|none|The start of nautical twilight in the evening| |nautical_twilight_end|string|true|none|The end of nautical twilight in the evening| |astronomical_twilight_begin|string|true|none|The start of astronomical twilight in the evening| |astronomical_twilight_end|string|true|none|The end of astronomical twilight in the evening| ### ErrorResponse Standard error envelope returned by the API on failed requests. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |error|string|false|none|Short error category or exception type.| |message|string|true|none|Human-readable error message describing the failure.| |path|string|false|none|API endpoint path that produced the error.| |status|integer|false|none|HTTP status code returned with the error.| |timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|