Astronomy

Solar event times for any location and date, including sunrise, sunset, twilight periods, and photography windows.

Lunar event times and phase information for any location and date.

Standards Used

ISO 8601
IANA TZDB
GeoNames
IATA

Polar Regions#

When the sun doesn't rise or set, sunrise and sunset are null and polar_condition indicates why:

midnight_sun - sun doesn't set (summer in polar latitudes)
polar_night - sun doesn't rise (winter in polar latitudes)

The Astronomy Objects#

Sun Object#

Field	Type	Required	Description
blue_hour	null \| object	No
date	string	Yes	Date (ISO 8601). Example: `2024-06-21`
day_length	string	Yes	Day length as "HH:MM". Example: `15:07`
day_length_minutes	integer (int32)	Yes	Day length in minutes. Example: `907`
golden_hour	null \| object	No
location	object	Yes	Location coordinates resolved from input.
latitude	number (double)	Yes	Latitude in decimal degrees. Example: `40.7128`
longitude	number (double)	Yes	Longitude in decimal degrees. Example: `-74.006`
polar_condition	string	No	Polar condition if applicable (midnight_sun or polar_night). Example: `midnight_sun`
solar_noon	string	Yes	Solar noon time (ISO 8601). Example: `2024-06-21T12:57:00-04:00`
sunrise	string	No	Sunrise time (ISO 8601), null if sun doesn't rise. Example: `2024-06-21T05:24:00-04:00`
sunset	string	No	Sunset time (ISO 8601), null if sun doesn't set. Example: `2024-06-21T20:31:00-04:00`
timezone	string	Yes	IANA timezone used for times. Example: `America/New_York`
twilight	null \| object	No

Moon Object#

Field	Type	Required	Description
age_days	number (double)	Yes	Days since new moon. Example: `14.5`
date	string	Yes	Date (ISO 8601). Example: `2024-06-21`
illumination	number (double)	Yes	Illumination percentage (0-100). Example: `99.5`
location	object	Yes	Location coordinates resolved from input.
latitude	number (double)	Yes	Latitude in decimal degrees. Example: `40.7128`
longitude	number (double)	Yes	Longitude in decimal degrees. Example: `-74.006`
moonrise	string	No	Moonrise time (ISO 8601), null if moon doesn't rise. Example: `2024-06-21T19:45:00-04:00`
moonset	string	No	Moonset time (ISO 8601), null if moon doesn't set. Example: `2024-06-22T04:30:00-04:00`
phase	string	Yes	Phase identifier. Example: `full`
phase_name	string	Yes	Human-readable phase name. Example: `Full Moon`
timezone	string	Yes	IANA timezone used for times. Example: `America/New_York`

Moon Phase Values#

Schema 'MoonPhase' not found in OpenAPI specification.

Location Object#

Field	Type	Required	Description
latitude	number (double)	Yes	Latitude in decimal degrees. Example: `40.7128`
longitude	number (double)	Yes	Longitude in decimal degrees. Example: `-74.006`

Twilight Object#

Field	Type	Required	Description
astronomical	object	Yes	Twilight period with dawn and dusk times.
dawn	string	No	Dawn time (ISO 8601). Example: `2024-06-21T04:30:00-04:00`
dusk	string	No	Dusk time (ISO 8601). Example: `2024-06-21T21:15:00-04:00`
civil	object	Yes	Twilight period with dawn and dusk times.
dawn	string	No	Dawn time (ISO 8601). Example: `2024-06-21T04:30:00-04:00`
dusk	string	No	Dusk time (ISO 8601). Example: `2024-06-21T21:15:00-04:00`
nautical	object	Yes	Twilight period with dawn and dusk times.
dawn	string	No	Dawn time (ISO 8601). Example: `2024-06-21T04:30:00-04:00`
dusk	string	No	Dusk time (ISO 8601). Example: `2024-06-21T21:15:00-04:00`

PhotoHour Object#

Used for both golden_hour and blue_hour fields, containing morning and evening time windows.

Field	Type	Required	Description
evening	null \| object	No
morning	null \| object	No

Endpoints#

Path Parameters

Parameter	Type	Required	Description
locationpath	string	Yes	Coordinates (lat,lon), city GeoNames ID, or airport IATA code

Query Parameters

Parameter	Type	Required	Description
datequery	string	No	Date (ISO 8601, YYYY-MM-DD). Defaults to today. Example: `2024-06-21`

Response

Field	Type	Required	Description
age_days	number (double)	Yes	Days since new moon. Example: `14.5`
date	string	Yes	Date (ISO 8601). Example: `2024-06-21`
illumination	number (double)	Yes	Illumination percentage (0-100). Example: `99.5`
location	object	Yes	Location coordinates resolved from input.
latitude	number (double)	Yes	Latitude in decimal degrees. Example: `40.7128`
longitude	number (double)	Yes	Longitude in decimal degrees. Example: `-74.006`
moonrise	string	No	Moonrise time (ISO 8601), null if moon doesn't rise. Example: `2024-06-21T19:45:00-04:00`
moonset	string	No	Moonset time (ISO 8601), null if moon doesn't set. Example: `2024-06-22T04:30:00-04:00`
phase	string	Yes	Phase identifier. Example: `full`
phase_name	string	Yes	Human-readable phase name. Example: `Full Moon`
timezone	string	Yes	IANA timezone used for times. Example: `America/New_York`

Example Request

const response = await fetch(
  'https://worlddataapi.com/v1/moon/40.7128,-74.0060?date=2024-06-21',
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();

import requests

response = requests.get(
    'https://worlddataapi.com/v1/moon/40.7128,-74.0060',
    params={
        'date': '2024-06-21'
    },
    headers={
        'X-API-Key': 'YOUR_API_KEY'
    }
)

data = response.json()

curl "https://worlddataapi.com/v1/moon/40.7128,-74.0060?date=2024-06-21"
  -H "X-API-Key: YOUR_API_KEY"

Error Responses

Status	Description
400	Invalid location or date
402	Premium subscription required
404	Location not found
429	Rate limit exceeded

Path Parameters

Parameter	Type	Required	Description
locationpath	string	Yes	Coordinates (lat,lon), city GeoNames ID, or airport IATA code

Query Parameters

Parameter	Type	Required	Description
datequery	string	No	Date (ISO 8601, YYYY-MM-DD). Defaults to today. Example: `2024-06-21`

Response

Field	Type	Required	Description
blue_hour	null \| object	No
date	string	Yes	Date (ISO 8601). Example: `2024-06-21`
day_length	string	Yes	Day length as "HH:MM". Example: `15:07`
day_length_minutes	integer (int32)	Yes	Day length in minutes. Example: `907`
golden_hour	null \| object	No
location	object	Yes	Location coordinates resolved from input.
latitude	number (double)	Yes	Latitude in decimal degrees. Example: `40.7128`
longitude	number (double)	Yes	Longitude in decimal degrees. Example: `-74.006`
polar_condition	string	No	Polar condition if applicable (midnight_sun or polar_night). Example: `midnight_sun`
solar_noon	string	Yes	Solar noon time (ISO 8601). Example: `2024-06-21T12:57:00-04:00`
sunrise	string	No	Sunrise time (ISO 8601), null if sun doesn't rise. Example: `2024-06-21T05:24:00-04:00`
sunset	string	No	Sunset time (ISO 8601), null if sun doesn't set. Example: `2024-06-21T20:31:00-04:00`
timezone	string	Yes	IANA timezone used for times. Example: `America/New_York`
twilight	null \| object	No

Example Request

const response = await fetch(
  'https://worlddataapi.com/v1/sun/40.7128,-74.0060?date=2024-06-21',
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();

import requests

response = requests.get(
    'https://worlddataapi.com/v1/sun/40.7128,-74.0060',
    params={
        'date': '2024-06-21'
    },
    headers={
        'X-API-Key': 'YOUR_API_KEY'
    }
)

data = response.json()

curl "https://worlddataapi.com/v1/sun/40.7128,-74.0060?date=2024-06-21"
  -H "X-API-Key: YOUR_API_KEY"

Error Responses

Status	Description
400	Invalid location or date
402	Premium subscription required
404	Location not found
429	Rate limit exceeded

Standards Used

Polar Regions#

The Astronomy Objects#

Sun Object#

Moon Object#

Moon Phase Values#

Location Object#

Twilight Object#

PhotoHour Object#

Endpoints#

Path Parameters

Query Parameters

Response

Example Request

Error Responses

Path Parameters

Query Parameters

Response

Example Request

Error Responses

Related

Related APIs