Astronomy

Get sun and moon data including sunrise, sunset, moonrise, moonset, moon phases, and day length for any location

Overview

This endpoint provides astronomical data for any geographic location. You can get sunrise/sunset times, moonrise/moonset times, moon phase information, and day length calculations.

The endpoint returns:

  • Sunrise and sunset times
  • Solar noon time
  • Day length in hours
  • Moonrise and moonset times
  • Moon phase (numeric value and name)
  • Moon illumination percentage

Pricing

📊 1 Credit per Request

Each request costs 1 data credit and counts as a billable request.

Endpoint

GET /astronomy?lat={latitude}&lng={longitude}
GET /astronomy?coords={latitude},{longitude}
GET /astronomy?coords={latitude},{longitude}&date={ISO_date}

Query Parameters

ParameterTypeRequiredDescription
latnumberYes*Latitude (-90 to 90). Required if coords is not provided
lngnumberYes*Longitude (-180 to 180). Required if coords is not provided
coordsstringYes*Coordinates as "lat,lng". Also supports ":" and "|" separators. Required if lat/lng are not provided
datestringNoDate in ISO 8601 format (e.g., "2025-06-21"). Default: today

*Either lat+lng or coords must be provided.

Response Format

{
  "coordinates": {
    "lat": 48.8566,
    "lng": 2.3522
  },
  "date": "2025-06-21",
  "sun": {
    "sunrise": "2025-06-21T03:47:00.000Z",
    "sunset": "2025-06-21T19:57:00.000Z",
    "solarNoon": "2025-06-21T11:52:00.000Z",
    "dayLengthHours": 16.17
  },
  "moon": {
    "moonrise": "2025-06-21T01:30:00.000Z",
    "moonset": "2025-06-21T14:15:00.000Z",
    "phase": 0.25,
    "illumination": 0.5,
    "phaseName": "First Quarter"
  }
}

Response Fields

Sun Data

FieldTypeDescription
sun.sunrisestringISO 8601 datetime of sunrise
sun.sunsetstringISO 8601 datetime of sunset
sun.solarNoonstringISO 8601 datetime of solar noon
sun.dayLengthHoursnumberLength of day in hours

Moon Data

FieldTypeDescription
moon.moonrisestringISO 8601 datetime of moonrise
moon.moonsetstringISO 8601 datetime of moonset
moon.phasenumberMoon phase value (0 to 1)
moon.illuminationnumberMoon illumination percentage (0 to 1)
moon.phaseNamestringHuman-readable moon phase name

Moon Phase Values

ValuePhase Name
0New Moon
~0.125Waxing Crescent
0.25First Quarter
~0.375Waxing Gibbous
0.5Full Moon
~0.625Waning Gibbous
0.75Last Quarter
~0.875Waning Crescent

Example Requests

Using lat/lng Parameters

curl -X GET "https://api.boxapi.com/astronomy?lat=48.8566&lng=2.3522" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Using coords Parameter

curl -X GET "https://api.boxapi.com/astronomy?coords=48.8566,2.3522" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

With Specific Date

curl -X GET "https://api.boxapi.com/astronomy?coords=40.7128,-74.0060&date=2025-06-21" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Alternate Coordinate Separators

# Using colon separator
curl -X GET "https://api.boxapi.com/astronomy?coords=48.8566:2.3522" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Using pipe separator
curl -X GET "https://api.boxapi.com/astronomy?coords=48.8566|2.3522" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Usage Examples

JavaScript/Node.js

// Get astronomy data for Paris
const response = await fetch(
  'https://api.boxapi.com/astronomy?lat=48.8566&lng=2.3522',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(`Date: ${data.date}`);
console.log(`Sunrise: ${data.sun.sunrise}`);
console.log(`Sunset: ${data.sun.sunset}`);
console.log(`Day length: ${data.sun.dayLengthHours.toFixed(1)} hours`);
console.log(`Moon phase: ${data.moon.phaseName} (${(data.moon.illumination * 100).toFixed(0)}% illuminated)`);

// Get data for a specific date
const summerSolstice = await fetch(
  'https://api.boxapi.com/astronomy?coords=40.7128,-74.0060&date=2025-06-21',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const solsticeData = await summerSolstice.json();
console.log(`Summer solstice day length: ${solsticeData.sun.dayLengthHours.toFixed(1)} hours`);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Get astronomy data for Paris
response = requests.get(
    'https://api.boxapi.com/astronomy?lat=48.8566&lng=2.3522',
    headers=headers
)
data = response.json()
print(f"Date: {data['date']}")
print(f"Sunrise: {data['sun']['sunrise']}")
print(f"Sunset: {data['sun']['sunset']}")
print(f"Day length: {data['sun']['dayLengthHours']:.1f} hours")
print(f"Moon phase: {data['moon']['phaseName']} ({data['moon']['illumination']*100:.0f}% illuminated)")

# Get data for a specific date
solstice_response = requests.get(
    'https://api.boxapi.com/astronomy?coords=40.7128,-74.0060&date=2025-06-21',
    headers=headers
)
solstice_data = solstice_response.json()
print(f"Summer solstice day length: {solstice_data['sun']['dayLengthHours']:.1f} hours")

PHP

<?php
$apiKey = 'YOUR_API_KEY';

// Get astronomy data for Paris
$ch = curl_init('https://api.boxapi.com/astronomy?lat=48.8566&lng=2.3522');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

echo "Date: {$data['date']}\n";
echo "Sunrise: {$data['sun']['sunrise']}\n";
echo "Sunset: {$data['sun']['sunset']}\n";
echo "Day length: " . number_format($data['sun']['dayLengthHours'], 1) . " hours\n";
echo "Moon phase: {$data['moon']['phaseName']} (" . round($data['moon']['illumination'] * 100) . "% illuminated)\n";
?>

Error Responses

Missing Coordinates

{
  "error": "Missing required parameters: lat and lng (or coords)",
  "usage": "GET /astronomy?lat=48.8566&lng=2.3522"
}

HTTP Status: 400 Bad Request

Invalid Coordinates

{
  "error": "Invalid latitude: must be between -90 and 90"
}

HTTP Status: 400 Bad Request

Invalid Date

{
  "error": "Invalid date format. Use ISO 8601 format (e.g., 2025-06-21)"
}

HTTP Status: 400 Bad Request

Authentication Error

{
  "error": "Unauthorized"
}

HTTP Status: 401 Unauthorized

Rate Limit Exceeded

{
  "error": "IP blocked",
  "statusCode": 429
}

HTTP Status: 429 Too Many Requests

Rate Limits

The following rate limits apply per IP address:

  • 10,000 requests per minute for successful responses (2xx status codes)
  • 60 requests per minute for client errors (4xx status codes)
  • 60 requests per minute for server errors (5xx status codes)

⚠️ If you exceed these limits, your IP will be temporarily blocked and you'll receive a 429 status code.

Important Notes

  • All times are returned in UTC (ISO 8601 format)
  • The coords parameter supports three separators: comma (,), colon (:), and pipe (|)
  • Moon phase is a continuous value from 0 to 1, where 0 = New Moon and 0.5 = Full Moon
  • Day length is calculated based on the geographic coordinates and date
  • For locations above the Arctic Circle or below the Antarctic Circle, sunrise/sunset may not occur during certain dates

Use Cases

The Astronomy API is ideal for:

  • 🌅 Photography apps planning golden hour and blue hour shoots
  • 🌙 Outdoor planning for camping, hiking, and stargazing
  • 🏗️ Construction & solar calculating sunlight hours for solar panels
  • 🌾 Agriculture planning activities around daylight and moon phases
  • 📱 Weather apps displaying sunrise/sunset and moon data
  • 🎣 Fishing & hunting apps using moon phase predictions