Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

🚀 Moon API Reference

Base URL: https://api.moon.lunar.dev/v1
Version: 1.0.0 (stable since 4.51 billion years ago)
Status: All systems operational (uptime: 99.9999999999%)
Rate limit: None. The Moon does not throttle.
Auth: None. The Moon is open access.
Response format: JSON

Overview

The Moon API is a RESTful interface to Earth's only natural satellite. Every endpoint returns real astronomical data — no mocks, no stubs, no sandbox environment. The Moon has been serving requests continuously for 4.51 billion years with zero planned downtime.

Note

The Moon is always half-illuminated by the Sun. What we call a "phase" is simply the portion of that illuminated half visible from Earth. The Moon doesn't change — your viewing angle does.

Authentication

Authorization: None required

The Moon has no authentication, no API keys, no OAuth flow, and no rate limiting. It's the most open API in the Solar System. You don't need to sign up. You don't need to log in. You just need to look up.

Warning

The Moon API does not use HTTPS. It uses Heliophysical Transfer Protocol (HTTP/Star). Encryption is provided by 150 million km of vacuum between you and the Sun. Man-in-the-middle attacks require physically being between Earth and the Moon, which is expensive and generally not worth it.

Rate Limiting

X-RateLimit-Limit: ∞
X-RateLimit-Remaining: ∞
X-RateLimit-Reset: never

The Moon does not implement rate limiting. You can query it as often as you like. However, if you stare at it too long, your eyes may hurt. This is a client-side issue, not an API issue.

Endpoints

Method Endpoint Description
GET /phase Current lunar phase and illumination fraction
GET /distance Current distance from Earth
GET /rise Moonrise and moonset times for a location
GET /surface Surface conditions (temperature, gravity, radiation)
GET /tides Tidal effect at a given location
POST /landing Register a landing on the surface
DELETE /crater Remove an impact crater (not recommended)
GET /eclipses Upcoming eclipse schedule
GET /health Service health check

GET /phase

Returns the current lunar phase, illuminated fraction, and phase name as seen from Earth.

Request

GET /v1/phase?date=2026-07-29&hemisphere=northern
Parameter Type Required Description
date string (ISO 8601) No Date to query. Defaults to now.
hemisphere string No northern (default) or southern. Affects waxing/waning orientation.

Response

{
  "phase": {
    "name": "Waxing Gibbous",
    "code": "WAXING_GIBBOUS",
    "illuminated_fraction": 0.73,
    "phase_angle": 2.24,
    "is_waxing": true,
    "days_since_new": 10.2,
    "days_until_full": 4.3,
    "next_phase": "Full Moon",
    "next_phase_date": "2026-08-02T12:14:00Z"
  },
  "geometry": {
    "sun_earth_moon_angle_deg": 131.4,
    "moon_angular_diameter_arcmin": 31.5,
    "distance_km": 384400
  },
  "request": {
    "date": "2026-07-29T00:00:00Z",
    "hemisphere": "northern"
  }
}

Phase Values

Code Name Illuminated % Appearance (N. Hemisphere)
NEW New Moon 0% Not visible
WAXING_CRESCENT Waxing Crescent 1–49% Right side lit (D shape)
FIRST_QUARTER First Quarter 50% Right half lit
WAXING_GIBBOUS Waxing Gibbous 51–99% Mostly lit, right side
FULL Full Moon 100% Fully illuminated
WANING_GIBBOUS Waning Gibbous 51–99% Mostly lit, left side
LAST_QUARTER Last Quarter 50% Left half lit
WANING_CRESCENT Waning Crescent 1–49% Left side lit (C shape)

Note

The Moon is always half-illuminated by the Sun. The "phase" is simply the fraction of that illuminated half that's visible from Earth. A "new Moon" isn't dark — it's just facing away from us. A "full Moon" isn't generating light — it's just fully facing us.

Tip

In the southern hemisphere, the illuminated side is mirrored: waxing crescent is lit on the left, waning on the right. The API handles this via the hemisphere parameter. The Moon doesn't change — your hemisphere does.

Errors

Status Error Cause
400 INVALID_DATE Date is outside the Moon's operational range (past 4.51 Ga or future >10,000 years)
400 INVALID_HEMISPHERE Must be northern or southern. The Moon does not recognize eastern or western.

GET /distance

Returns the current distance between Earth and Moon. Because the Moon's orbit is elliptical (eccentricity 0.0549), this value changes continuously.

Request

GET /v1/distance?date=2026-07-29
Parameter Type Required Description
date string (ISO 8601) No Date to query. Defaults to now.

Response

{
  "distance": {
    "current_km": 384400,
    "perigee_km": 363300,
    "apogee_km": 405500,
    "is_approaching": true,
    "rate_cm_per_year": 3.8,
    "semimajor_axis_km": 384748,
    "eccentricity": 0.0549
  },
  "visual": {
    "angular_diameter_arcmin": 31.1,
    "apparent_size_vs_average": 0.97,
    "is_supermoon": false
  },
  "fun_fact": "The Moon is moving away from Earth at 3.8 cm/year — about the rate your fingernails grow."
}

Distance Variations

    Apogee (405,500 km)          Perigee (363,300 km)
         ←─── 42,200 km range ───→

    ┌─────────────────────────────────────┐
    │                                     │
    │   ◄── Moon moves slower here        │
    │                                     │
    │         ┌─────┐                     │
    │         │Earth│                     │
    │         └─────┘                     │
    │                                     │
    │              Moon moves faster ──►  │
    │                                     │
    └─────────────────────────────────────┘

    This is Kepler's Second Law in action.
    The Moon does not negotiate with physics.

Important

The Moon drifts away at 3.8 cm per year due to tidal transfer of angular momentum. In ~600 million years, it will be too far to fully cover the Sun during eclipses. Total solar eclipses are a limited-time feature. No extension available.

Errors

Status Error Cause
418 I_AM_A_TEAPOT You asked the Moon for coffee. The Moon is not a teapot. (See: Russell's Teapot)

GET /rise

Returns moonrise and moonset times for a given location and date.

Request

GET /v1/rise?lat=40.7128&lon=-74.0060&date=2026-07-29
Parameter Type Required Description
lat float Yes Latitude (-90 to 90)
lon float Yes Longitude (-180 to 180)
date string (ISO 8601) No Date to query. Defaults to today.
timezone string No IANA timezone (e.g., America/New_York). Defaults to UTC.

Response

{
  "location": {
    "lat": 40.7128,
    "lon": -74.0060,
    "timezone": "America/New_York"
  },
  "date": "2026-07-29",
  "events": [
    {
      "event": "moonrise",
      "time": "2026-07-29T14:32:00-04:00",
      "azimuth_deg": 112.4
    },
    {
      "event": "moonset",
      "time": "2026-07-30T02:15:00-04:00",
      "azimuth_deg": 248.7
    }
  ],
  "visibility": {
    "visible_during_daytime": true,
    "max_altitude_deg": 67.2,
    "transit_time": "2026-07-29T20:23:00-04:00"
  },
  "note": "The Moon rises about 50 minutes later each day. This is not a bug — it's orbital mechanics."
}

Tip

The Moon rises ~50 minutes later each day because it's moved ~13° eastward in its orbit during one Earth rotation. Earth needs to rotate that extra 13° to bring the Moon back to the same position in the sky. 13° ÷ 360° × 24h ≈ 52 minutes. This is Kepler's gift to werewolf scheduling.

Errors

Status Error Cause
400 INVALID_COORDS Latitude/longitude out of range
404 LOCATION_NOT_FOUND Coordinates don't correspond to any known location. The Moon still sees you, though.
409 MOON_ALREADY_UP The Moon is already in the sky. Try again after moonset.

GET /surface

Returns current surface conditions at a specified location on the Moon.

Request

GET /v1/surface?lat=0&lon=0&date=2026-07-29

Response

{
  "location": {
    "lat": 0,
    "lon": 0,
    "region": "Near side equator"
  },
  "environment": {
    "temperature_c": {
      "current": 107,
      "min": -153,
      "max": 127
    },
    "gravity_m_s2": 1.62,
    "atmosphere": null,
    "radiation_dose_rem_per_day": 30,
    "solar_flare_warning": false
  },
  "surface": {
    "regolith_depth_m": 4.2,
    "rock_type": "basalt",
    "in_crater": false,
    "nearest_named_crater": "Copernicus",
    "nearest_crater_distance_km": 1200
  },
  "lighting": {
    "is_lunar_day": true,
    "sun_elevation_deg": 45.2,
    "earth_visible": true,
    "earth_phase": "Waning Crescent",
    "earth_angular_diameter_deg": 1.9
  }
}

Warning

Surface temperature swings 300°C between lunar day and night. There is no atmosphere to moderate this. No air, no weather, no wind chill — just raw thermal radiation. The Moon does not "feel like" any temperature. It IS that temperature.

Note

earth_phase is the phase of Earth as seen from the Moon — the complement of the Moon's phase from Earth. When it's a full Moon on Earth, it's a "new Earth" on the Moon, and vice versa.

GET /tides

Returns tidal data for a given coastal location.

Request

GET /v1/tides?lat=51.5074&lon=-0.1278&date=2026-07-29

Response

{
  "location": {
    "lat": 51.5074,
    "lon": -0.1278,
    "name": "London, UK"
  },
  "date": "2026-07-29",
  "moon_phase": "Waxing Gibbous",
  "tide_type": "neap",
  "tides": [
    {
      "type": "high",
      "time": "2026-07-29T06:12:00+01:00",
      "height_m": 5.4
    },
    {
      "type": "low",
      "time": "2026-07-29T12:34:00+01:00",
      "height_m": 0.8
    },
    {
      "type": "high",
      "time": "2026-07-29T18:45:00+01:00",
      "height_m": 5.6
    },
    {
      "type": "low",
      "time": "2026-07-30T01:02:00+01:00",
      "height_m": 0.6
    }
  ],
  "tidal_range_m": 4.9,
  "spring_or_neap": "neap",
  "explanation": "Neap tide: Moon is at quarter phase, Sun and Moon are at right angles, gravitational pulls partially cancel."
}

Tip

Spring tides (highest tides) occur at full and new Moon, when Sun and Moon pull together. Neap tides (lowest tides) occur at quarter Moon, when they pull at right angles and partially cancel. "Spring" has nothing to do with the season — it means "springing up." "Neap" comes from Old English meaning "scanty." The Moon did not name these tides. Humans did, and they chose confusing names.

POST /landing

Register a spacecraft landing on the Moon. Creates a new landing record.

Request

POST /v1/landing
Content-Type: application/json

{
  "mission_name": "Artemis III",
  "agency": "NASA",
  "crew": 4,
  "landing_site": {
    "lat": -85.0,
    "lon": 30.0,
    "name": "Shackleton Crater Rim"
  },
  "landed_at": "2027-09-01T12:00:00Z",
  "type": "crewed"
}

Response

{
  "landing_id": "artemis-iii-2027",
  "status": "registered",
  "landing_site": {
    "lat": -85.0,
    "lon": 30.0,
    "name": "Shackleton Crater Rim",
    "region": "Lunar South Pole",
    "has_water_ice": true,
    "permanently_lit": true
  },
  "crew": 4,
  "mission_number": 13,
  "previous_landing": "Apollo 17 (1972-12-11)",
  "warning": "You are the first humans to land on the Moon since 1972. Please do not leave litter. The Apollo sites are protected historical landmarks.",
  "etiquette": {
    "footprints": "Will last millions of years. Step carefully.",
    "flags": "Will bleach white within a few years due to UV radiation. The Moon does not care about your flag.",
    "golf": "Permitted. Previous record: ~40m by Alan Shepard, 1971."
  }
}

Important

The Outer Space Treaty (1967) prohibits national appropriation of the Moon. You cannot claim territory. You can leave equipment, but you cannot own the land. The Moon is a commons. Play nice.

Caution

Ensure your spacecraft has sufficient delta-v for the return trip. The Moon has no refueling stations yet. If you forget this, you will become a permanent resident. The Moon has no eviction process, but also no air, food, or water (except ice you'd need to mine yourself).

Errors

Status Error Cause
400 INVALID_LANDING_SITE Coordinates are not on the Moon's surface
402 PAYMENT_REQUIRED You forgot to bring a rocket. Rockets are not free.
409 SITE_OCCUPIED Landing site already has hardware (e.g., Apollo landing sites)
418 I_AM_A_TEAPOT You attempted to land a teapot. See: Russell's Teapot paradox.
503 NO_RETURN_FUEL Your spacecraft has insufficient delta-v for return. This is a critical error.

DELETE /crater

Removes an impact crater from the Moon's surface.

Request

DELETE /v1/crater?name=Tycho
Parameter Type Required Description
name string Yes IAU-approved crater name

Response

{
  "crater": "Tycho",
  "status": "deletion_denied",
  "reason": "Craters are permanent geological features. The Moon has no erosion, no weather, and no tectonic activity. This crater has been here for 108 million years and will remain for millions more.",
  "estimated_lifespan_years": 100000000,
  "alternative": "You cannot delete craters. You can create new ones, but that requires a meteor and is not recommended.",
  "http_status": 405,
  "allow": "GET"
}

Warning

This endpoint always returns 405 Method Not Allowed. You cannot delete craters. The Moon's surface is a 4-billion-year-old archive. There is no garbage collection, no erosion service, and no cleanup API. Craters are append-only. This is by design, not a bug.

Note

If you want to ADD a crater, you'd need to POST /impact — but that endpoint is deprecated and has been since the Late Heavy Bombardment (~3.8 billion years ago). The Moon is no longer accepting large impactors. Small ones still happen, but the Moon doesn't advertise the endpoint.

Errors

Status Error Cause
405 METHOD_NOT_ALLOWED Craters cannot be deleted. The Moon is append-only.
404 CRATER_NOT_FOUND No IAU-named crater with that name
403 FORBIDDEN You do not have permission to modify the Moon's surface. Nobody does.

GET /eclipses

Returns upcoming eclipse events.

Request

GET /v1/eclipses?type=all&count=5
Parameter Type Required Description
type string No solar, lunar, or all (default)
count int No Number of results (default 5, max 20)

Response

{
  "eclipses": [
    {
      "type": "lunar",
      "subtype": "total",
      "date": "2026-08-28",
      "visible_from": ["Americas", "Europe", "Africa"],
      "duration_totality_min": 82,
      "notes": "Blood Moon — Earth's atmosphere refracts red light onto the Moon."
    },
    {
      "type": "solar",
      "subtype": "annular",
      "date": "2026-02-17",
      "visible_from": ["Antarctica"],
      "duration_totality_min": 2.4,
      "notes": "Ring of fire. Moon near apogee — too far to fully cover the Sun."
    },
    {
      "type": "solar",
      "subtype": "total",
      "date": "2027-08-02",
      "visible_from": ["Spain", "North Africa", "Middle East"],
      "duration_totality_min": 6.23,
      "notes": "Longest totality until 2114. Book your travel now."
    }
  ],
  "disclaimer": "Eclipses are scheduled by celestial mechanics. They are not rescheduled for weather. Check your local forecast independently."
}

Tip

Solar eclipses occur because the Sun is ~400× larger than the Moon but also ~400× farther away — a temporary cosmic coincidence. In ~600 million years, the Moon will be too far for total solar eclipses. This endpoint will eventually return only annular eclipses. The Moon apologizes for the inconvenience.

GET /health

Service health check.

Request

GET /v1/health

Response

{
  "status": "operational",
  "uptime_years": 4510000000,
  "last_incident": "Late Heavy Bombardment (~3.8 Ga)",
  "incidents_since": 0,
  "orbit": "stable",
  "drift_rate_cm_per_year": 3.8,
  "mass_kg": 7.342e22,
  "reflectivity_albedo": 0.12,
  "fun_fact": "The Moon has been operational for 4.51 billion years with zero unplanned downtime. Your AWS instance could never."
}

SDK Examples

cURL

# Get current phase
curl https://api.moon.lunar.dev/v1/phase

# Get distance
curl https://api.moon.lunar.dev/v1/distance

# Register a landing
curl -X POST https://api.moon.lunar.dev/v1/landing \
  -H "Content-Type: application/json" \
  -d '{"mission_name": "My Backyard Rocket", "crew": 0, "type": "uncrewed"}'

# Try to delete a crater (spoiler: you can't)
curl -X DELETE https://api.moon.lunar.dev/v1/crater?name=Copernicus

Python

import requests

# Get current Moon phase
resp = requests.get("https://api.moon.lunar.dev/v1/phase")
phase = resp.json()
print(f"Moon is {phase['phase']['name']}, {phase['phase']['illuminated_fraction']*100:.1f}% illuminated")
# Output: Moon is Waxing Gibbous, 73.0% illuminated

# Check if it's a supermoon
dist = requests.get("https://api.moon.lunar.dev/v1/distance").json()
if dist["visual"]["is_supermoon"]:
    print("🌟 Supermoon tonight! (Not actually bigger. Your brain just thinks so.)")

JavaScript

// Get moonrise time
const res = await fetch("https://api.moon.lunar.dev/v1/rise?lat=35.6762&lon=139.6503");
const data = await res.json();
console.log(`Moonrise in Tokyo: ${data.events[0].time}`);
// Output: Moonrise in Tokyo: 2026-07-29T22:14:00+09:00

// The Moon does not support WebSocket. It's RESTful and that's final.

Changelog

Version Date Changes
1.0.0 4.51 Ga Initial release. Moon formed. API online.
1.0.1 ~4.4 Ga Crust solidified. Surface endpoints now return data.
1.1.0 ~4.2 Ga Large impact basins created. POST /impact endpoint added (now deprecated).
1.2.0 ~3.8 Ga Mare volcanism. New basalt surfaces added to /surface.
1.2.1 ~3.0 Ga Volcanism ended. No new maria. API stable.
1.3.0 ~1.0 Ga Magnetic dynamo stopped. radiation field updated in /surface.
1.3.1 1969-07-20 First API consumer landed. POST /landing endpoint used by Apollo 11.
1.3.2 1972-12-14 Last crewed landing. POST /landing has not been called since.
1.3.3 3.8 cm/yr Ongoing. Moon drifting away. Distance endpoint values slowly increasing.
2.0.0 ~600 My future Moon too far for total solar eclipses. GET /eclipses will return annular only. Breaking change.

⚠️ Known Limitations

Limitation Details
No WebSocket support The Moon is RESTful only. Real-time updates require polling.
No authentication Anyone can access the Moon. This is a feature, not a security issue.
No content negotiation JSON only. The Moon does not support XML, SOAP, or GraphQL.
DELETE not supported The Moon is append-only. You can add craters (via impact) but not remove them.
POST /landing requires hardware You need a functional rocket. The API cannot provide one.
Eclipse schedules may change Due to tidal deceleration, eclipse timing drifts over geological timescales. For short-term use (next 1,000 years), this is negligible.
No CORS headers The Moon predates browsers by 4.51 billion years. Use a proxy.
No pagination All responses are complete. The Moon does not truncate.

FAQ

"Can I fork this API?"

You can fork the repo, but you cannot fork the Moon. There is only one Moon. If you want a second one, you'll need a Giant Impact, and that voids your planet's warranty.

"Is there a sandbox environment?"

The Moon has been the production environment for 4.51 billion years. There is no staging. There is no sandbox. Every request hits production. This is fine because the Moon handles load gracefully.

"What happens when the Moon eventually drifts away?"

The GET /distance values will slowly increase. GET /eclipses will stop returning total solar eclipses around 600 million years from now. GET /tides will return weaker tidal ranges. The API will not shut down — it will just return different data. This is called "thermal drift" in the literal sense.

"Why is there no PATCH endpoint?"

The Moon's surface cannot be patched. Craters are permanent. Regolith is everywhere. You can add to the surface (via impact or landing) but you cannot modify existing features. The Moon is immutable by design.

License

MIT — the Moon is open source and belongs to everyone. See LICENSE.

Moon API Reference is an educational project. The Moon does not actually expose a REST API. But if it did, this is what it would look like. The astronomy is real; the endpoints are not.

About

🚀 Moon API Reference — a pretend REST API for Earth's Moon. Every endpoint teaches real astronomy.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors