SearchCtrl+K

Astronomy API Reference

Retrieve sunrise and sunset times, the current position of the moon, and other related information by specifying a location address, coordinates, or IP address.

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

Test

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.

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version 2.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v2.0/geolocation/astronomy?location=New+York%2C+US' \
  -H 'X-apiKey: API-KEY'

Response

{
  "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-08",
    "current_time": "08: 08: 18.082",
    "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": 26.829501780670096,
    "sun_distance": 152098283.03028187,
    "sun_azimuth": 82.61268450407698,
    "moon_phase": "LAST_QUARTER",
    "moonrise": "00: 20",
    "moonset": "14: 23",
    "moon_status": "-",
    "moon_altitude": 60.66467085334474,
    "moon_distance": 374925.11428302806,
    "moon_azimuth": 206.0655558233637,
    "moon_parallactic_angle": 20.026339165773148,
    "moon_illumination_percentage": "-42.36",
    "moon_angle": 278.78724636692596
  }
}

API Request

Query Parameters

The following parameters can be used in your API requests. All parameters are passed as query string parameters.

formatoptionalStringdefault: json

Response format: 'json' (default) or 'xml'.

locationoptionalStringdefault: New York, US

Extract astronomy information using location (preferably city)

latoptionalFloat

Latitude to extract astronomy information using location coordinates

longoptionalFloat

Longitude to extract astronomy information using location coordinates

ipoptionalString

IPv4 or IPv6 address to extract astronomy information using IP address

langoptionalStringdefault: 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 Simplified)
7.es (Spanish)
8.cs (Czech)
9.it (Italian)
10.ko (Korean)
11.fa (Persian)
12.pt (Portuguese)

dateoptionalString

Specific date (format YYYY-MM-DD) for which astronomy data is required

elevationoptionalFloatdefault: 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_zoneoptionalStringdefault:

Time zone to receive all time-based data in your preferred local time.

API Response Schema

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.

ip

Stringoptional

IPv4 or IPv6 address used for the lookup. Returned only when queried using the ip= parameter.

time_zone (String), date (String), current_time (String), mid_night (String), night_end (String), …

location_string (String), continent_code (String), continent_name (String), country_code2 (String), country_code3 (String), …

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Latitude must be between -90 and 90.

400

'999.999.999.999' is not an IP string literal.

400

You must provide date in the 'yyyy-MM-dd' format

404

We couldn't find the location (ZZZNOTEXIST). Try a city or state level location address only.

Astronomy API Reference

Retrieve sunrise and sunset times, the current position of the moon, and other related information by specifying a location address, coordinates, or IP address.

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

Test

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version 2.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v2.0/geolocation/astronomy?location=New+York%2C+US' \
  -H 'X-apiKey: API-KEY'

Response

{
  "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-08",
    "current_time": "08: 08: 18.082",
    "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": 26.829501780670096,
    "sun_distance": 152098283.03028187,
    "sun_azimuth": 82.61268450407698,
    "moon_phase": "LAST_QUARTER",
    "moonrise": "00: 20",
    "moonset": "14: 23",
    "moon_status": "-",
    "moon_altitude": 60.66467085334474,
    "moon_distance": 374925.11428302806,
    "moon_azimuth": 206.0655558233637,
    "moon_parallactic_angle": 20.026339165773148,
    "moon_illumination_percentage": "-42.36",
    "moon_angle": 278.78724636692596
  }
}

API Request

Query Parameters

The following parameters can be used in your API requests. All parameters are passed as query string parameters.

formatoptionalStringdefault: json

Response format: 'json' (default) or 'xml'.

locationoptionalStringdefault: New York, US

Extract astronomy information using location (preferably city)

latoptionalFloat

Latitude to extract astronomy information using location coordinates

longoptionalFloat

Longitude to extract astronomy information using location coordinates

ipoptionalString

IPv4 or IPv6 address to extract astronomy information using IP address

langoptionalStringdefault: 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 Simplified)
7.es (Spanish)
8.cs (Czech)
9.it (Italian)
10.ko (Korean)
11.fa (Persian)
12.pt (Portuguese)

dateoptionalString

Specific date (format YYYY-MM-DD) for which astronomy data is required

elevationoptionalFloatdefault: 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_zoneoptionalStringdefault:

Time zone to receive all time-based data in your preferred local time.

API Response Schema

ip

Stringoptional

IPv4 or IPv6 address used for the lookup. Returned only when queried using the ip= parameter.

time_zone (String), date (String), current_time (String), mid_night (String), night_end (String), …

location_string (String), continent_code (String), continent_name (String), country_code2 (String), country_code3 (String), …

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Latitude must be between -90 and 90.

400

'999.999.999.999' is not an IP string literal.

400

You must provide date in the 'yyyy-MM-dd' format

404

We couldn't find the location (ZZZNOTEXIST). Try a city or state level location address only.

Quick Links

Quick Links

Astronomy API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Error Status & Codes

Docs

Integrations

Pricing & Accounts

Quick Links

Quick Links

Astronomy API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Error Status & Codes

Docs

Integrations

Pricing & Accounts