Moon API Documentation

Overview

Moon API provides accurate and real-time lunar data through a RESTful API. It offers a range of endpoints to retrieve moon phases, lunar data, and astronomical calculations. Whether you're building a lunar-themed application, planning an event, or simply curious about the moon, Moon API is your go-to source for lunar information.

Getting Started

🌕Try Live DemoInteractive Astronomical Dashboard 🔑Get API KeyStart Building

To get started with Moon API, follow these simple steps:

Sign up for an account on our platform.
Generate an API key from your account dashboard.
Use the API key in your API requests to authenticate.

Authentication

All API requests must include an API key. You can add the API key to your requests in the following ways:

As a query parameter: ?api_key=your_api_key
As a header: Authorization: Bearer your_api_key

Endpoints

Moon API offers a variety of endpoints to cater to different needs and plans. Below are the available endpoints:

GET /basic

All Plans

Get basic moon data including phase name and stage.

Query Parameters:

Parameter	Type	Required	Description	Plan Availability
lat	number	optional	Latitude for location-specific data	Basic: Default only Pro: ✅ (coarse) Ultra: ✅ (fine) Mega: ✅ (fine)
lon	number	optional	Longitude for location-specific data	Basic: Default only Pro: ✅ (coarse) Ultra: ✅ (fine) Mega: ✅ (fine)

Response:

{
  "phase_name": "Waning crescent",
  "stage": "waning",
  "illumination": "17%",
  "days_until_next_full_moon": 18,
  "days_until_next_new_moon": 4
}

docs.apiDocs.fieldDescriptions

phase_name: (string) Name of the current moon phase
stage: (string) Stage of the moon's cycle (waxing/waning)
days_until_next_full_moon: (integer) Days until next full moon
days_until_next_new_moon: (integer) Days until next new moon

GET /advanced

All Plans

Get comprehensive moon data with detailed astronomical information.

Query Parameters:

Parameter	Type	Required	Description	Plan Availability
lat	number	optional	Latitude for location-specific data	Basic: Default only Pro: ✅ (coarse) Ultra: ✅ (fine) Mega: ✅ (fine)
lon	number	optional	Longitude for location-specific data	Basic: Default only Pro: ✅ (coarse) Ultra: ✅ (fine) Mega: ✅ (fine)
timestamp	number	optional	Unix timestamp for historical/future data	Basic: ✅ (30 days) Pro: ✅ (1 year) Ultra: ✅ (2 years) Mega: ✅ (27 years)

Response:

{
  "timestamp": 1768384329,
  "datestamp": "Wed, 14 Jan 2026 09:52:09 +0000",
  "plan": "MEGA",
  "sun": {
    "sunrise": 1768377636,
    "sunrise_timestamp": "08:00",
    "sunset": 1768407535,
    "sunset_timestamp": "16:18",
    "solar_noon": "12:09",
    "day_length": "08:18",
    "position": {
      "altitude": 11.244371,
      "azimuth": 147.588568,
      "distance": 147150665085.64124
    },
    "next_solar_eclipse": {
      "timestamp": 1771329600,
      "datestamp": "Tue, 17 Feb 2026 12:00:00 +0000",
      "type": "Annular Solar Eclipse",
      "visibility_regions": "s Argentina & Chile, s Africa, Antarctica ; [Annular: Antarctica]"
    },
    "next_transit": {
      "timestamp": 1983944460,
      "datestamp": "Sat, 13 Nov 2032 07:41:00 +0000",
      "planet": "Mercury",
      "type": "Mercury Transit",
      "visibility_regions": "Americas, Europe, Africa, Asia, Australia (visible where Sun is above horizon)"
    }
  },
  "moon": {
    "phase": 0.8515761305,
    "phase_name": "Waning crescent",
    "major_phase": "New Moon",
    "stage": "waning",
    "illumination": "17%",
    "age_days": 25,
    "lunar_cycle": "17.48%",
    "emoji": "🌒",
    "zodiac": {
      "sun_sign": "Capricorn",
      "moon_sign": "Sagittarius"
    },
    "moonrise": "03:41",
    "moonrise_timestamp": 1768275670,
    "moonset": "11:17",
    "moonset_timestamp": 1768216633,
    "detailed": {
      "position": {
        "altitude": 9.536523,
        "azimuth": 197.876066,
        "distance": 405242987.277072,
        "parallactic_angle": 29.033395,
        "phase_angle": 130.57
      },
      "visibility": {
        "visible_hours": 16,
        "best_viewing_time": "03:41",
        "visibility_rating": "Fair",
        "illumination": "17.48%",
        "viewing_conditions": {
          "phase_quality": "Low illumination, challenging for detail observation",
          "recommended_equipment": {
            "filters": "No filters needed",
            "telescope": "4-inch or larger recommended",
            "best_magnification": "High magnification (100-200x) for crater detail"
          }
        }
      },
      "upcoming_phases": {
        "new_moon": {
          "last": {
            "timestamp": 1766194997,
            "datestamp": "Sat, 20 Dec 2025 01:43:17 +0000",
            "days_ago": 25
          },
          "next": {
            "timestamp": 1768765914,
            "datestamp": "Sun, 18 Jan 2026 19:51:54 +0000",
            "days_ahead": 4
          }
        },
        "first_quarter": {
          "last": {
            "timestamp": 1766862588,
            "datestamp": "Sat, 27 Dec 2025 19:09:48 +0000",
            "days_ago": 17
          },
          "next": {
            "timestamp": 1769402840,
            "datestamp": "Mon, 26 Jan 2026 04:47:20 +0000",
            "days_ahead": 11
          }
        },
        "full_moon": {
          "last": {
            "timestamp": 1767434570,
            "datestamp": "Sat, 03 Jan 2026 10:02:50 +0000",
            "days_ago": 10,
            "name": "Wolf Moon",
            "description": "Named after the howling wolves often heard during this time."
          },
          "next": {
            "timestamp": 1769983750,
            "datestamp": "Sun, 01 Feb 2026 22:09:10 +0000",
            "days_ahead": 18,
            "name": "Snow Moon",
            "description": "Reflects the cold snowy weather of this month."
          }
        },
        "last_quarter": {
          "last": {
            "timestamp": 1768060100,
            "datestamp": "Sat, 10 Jan 2026 15:48:20 +0000",
            "days_ago": 3
          },
          "next": {
            "timestamp": 1770640983,
            "datestamp": "Mon, 09 Feb 2026 12:43:03 +0000",
            "days_ahead": 26
          }
        }
      },
      "illumination_details": {
        "percentage": 17.48,
        "visible_fraction": 0.1748,
        "phase_angle": 130.57
      }
    }
  },
  "events": {
    "moonrise_visible": true,
    "moonset_visible": true,
    "optimal_viewing_period": {
      "start_time": "03:41",
      "end_time": "11:17",
      "duration_hours": 16,
      "viewing_quality": "Good for general observation",
      "recommendations": [
        "Visible most of the night",
        "Good for general lunar observation"
      ]
    }
  },
  "next_lunar_eclipse": {
    "timestamp": 1772537640,
    "datestamp": "Tue, 03 Mar 2026 11:34:00 +0000",
    "type": "Total Lunar Eclipse",
    "visibility_regions": "eastern Asia, Australia, Pacific, Americas"
  },
  "next_eclipse": {
    "timestamp": 1771329600,
    "datestamp": "Tue, 17 Feb 2026 12:00:00 +0000",
    "type": "Annular Solar Eclipse",
    "visibility_regions": "s Argentina & Chile, s Africa, Antarctica",
    "category": "solar",
    "countdown": {
      "days": 28,
      "hours": 18,
      "minutes": 51,
      "seconds": 22,
      "total_seconds": 2487082
    }
  },
  "note": "Using default London coordinates. Upgrade from BASIC plan to use custom coordinates.",
  "latitude": "51.50740",
  "longitude": "-0.12780"
}

docs.apiDocs.fieldDescriptions

timestamp: (integer) UNIX timestamp of the moon phase calculation
datestamp: (string) Date and time in UTC format
plan: (string) Current API plan level (BASIC, PRO, ULTRA, MEGA)
sun: (object) Solar data including:
- sunrise: (integer) UNIX timestamp for today's sunrise
- sunrise_timestamp: (string) The time of sunrise (HH:mm)
- sunset: (integer) UNIX timestamp for today's sunset
- sunset_timestamp: (string) The time of sunset (HH:mm)
- solar_noon: (string) The time when the sun reaches its highest point
- day_length: (string) Duration of daylight (HH:mm)
- position: (object) Current sun position data:
  - altitude: (float) The altitude of the sun above horizon in degrees
  - azimuth: (float) The azimuth of the sun's position in degrees
  - distance: (float) The distance between Earth and sun in kilometers
- next_solar_eclipse: (object) Next solar eclipse details (ULTRA/MEGA plans):
  - timestamp: (integer) UNIX timestamp of next solar eclipse
  - datestamp: (string) Date and time of next solar eclipse
  - type: (string) Type of solar eclipse (Total, Partial, Annular)
  - visibility_regions: (string) Regions where the eclipse will be visible
- next_transit: (object) Next planetary transit details (ULTRA/MEGA plans):
  - timestamp: (integer) UNIX timestamp of next transit
  - datestamp: (string) Date and time of next transit
  - planet: (string) Planet transiting (Mercury or Venus)
  - type: (string) Type of transit (Mercury Transit or Venus Transit)
  - visibility_regions: (string) Regions where the transit will be visible
moon: (object) Lunar data including:
- phase: (float) Moon phase as a number between 0 and 1
- phase_name: (string) Name of the current moon phase
- major_phase: (string) Major phase name (New Moon, First Quarter, etc)
- stage: (string) Stage of the moon's cycle (waxing/waning)
- illumination: (string) Percentage of moon's surface illuminated
- age_days: (integer) Age of the moon in days since new moon
- lunar_cycle: (string) Percentage through lunar cycle
- emoji: (string) Moon phase emoji (🌑, 🌒, 🌓, etc)
- zodiac: (object) Zodiac information:
  - sun_sign: (string) Current zodiac sign of the sun
  - moon_sign: (string) Current zodiac sign of the moon
- moonrise: (string) Time of moonrise (HH:mm)
- moonrise_timestamp: (integer) UNIX timestamp for moonrise
- moonset: (string) Time of moonset (HH:mm)
- moonset_timestamp: (integer) UNIX timestamp for moonset
- detailed: (object) Detailed moon information:
  - position: (object) Current position details:
    - altitude: (float) Current altitude of the moon in degrees
    - azimuth: (float) Current azimuth of the moon in degrees
    - distance: (float) Distance between Earth and moon in kilometers
    - parallactic_angle: (float) The parallactic angle of the moon in degrees
    - phase_angle: (float) Current phase angle in degrees
  - visibility: (object) Visibility information:
    - visible_hours: (integer) Number of hours the moon is visible
    - best_viewing_time: (string) Best time for moon observation (HH:mm)
    - visibility_rating: (string) Overall visibility rating
    - illumination: (string) Current illumination percentage
    - viewing_conditions: (object) Viewing conditions:
      - phase_quality: (string) Description of viewing quality for current phase
      - recommended_equipment: (object) Equipment recommendations:
        filters: (string) Recommended filters for observation
        telescope: (string) Recommended telescope specifications
        best_magnification: (string) Recommended magnification range
  - upcoming_phases: (object) Upcoming moon phases:
    - new_moon: (object) New moon timings:
      - last: (object) Details of last new moon (timestamp, datestamp, days_ago)
      - next: (object) Details of next new moon (timestamp, datestamp, days_ahead)
    - first_quarter: (object) First quarter timings:
      - last: (object) Details of last first quarter (timestamp, datestamp, days_ago)
      - next: (object) Details of next first quarter (timestamp, datestamp, days_ahead)
    - full_moon: (object) Full moon timings:
      - last: (object) Details of last full moon including name and description
      - next: (object) Details of next full moon including name and description
    - last_quarter: (object) Last quarter timings:
      - last: (object) Details of last quarter (timestamp, datestamp, days_ago)
      - next: (object) Details of next last quarter (timestamp, datestamp, days_ahead)
  - illumination_details: (object) Detailed illumination data:
    - percentage: (float) Precise illumination percentage
    - visible_fraction: (float) Visible fraction of the moon's surface
    - phase_angle: (float) Current phase angle in degrees
events: (object) Moon event information:
- moonrise_visible: (boolean) Whether moonrise is visible from location
- moonset_visible: (boolean) Whether moonset is visible from location
- optimal_viewing_period: (object) Best viewing details:
  - start_time: (string) Start of optimal viewing period (HH:mm)
  - end_time: (string) End of optimal viewing period (HH:mm)
  - duration_hours: (float) Duration of optimal viewing period in hours
  - viewing_quality: (string) Description of viewing conditions
  - recommendations: (array) List of viewing recommendations
next_lunar_eclipse: (object) Next lunar eclipse details (ULTRA/MEGA plans):
- timestamp: (integer) UNIX timestamp of next lunar eclipse (maximum eclipse time)
- datestamp: (string) Date and time of next lunar eclipse
- type: (string) Type of lunar eclipse (Total, Partial, Penumbral)
- visibility_regions: (string) Regions where the eclipse will be visible
next_eclipse: (object) Next upcoming eclipse with live countdown (ULTRA/MEGA plans):
- timestamp: (integer) UNIX timestamp of next eclipse (solar or lunar, whichever comes first)
- datestamp: (string) Date and time of next eclipse
- type: (string) Type of eclipse (e.g., "Annular Solar Eclipse", "Total Lunar Eclipse")
- visibility_regions: (string) Regions where the eclipse will be visible
- category: (string) Whether this is a "solar" or "lunar" eclipse
- countdown: (object) Live countdown timer:
  - days: (integer) Days until eclipse
  - hours: (integer) Hours until eclipse
  - minutes: (integer) Minutes until eclipse
  - seconds: (integer) Seconds until eclipse
  - total_seconds: (integer) Total seconds until eclipse
note: (string) Additional information about location usage
latitude: (string) Latitude of the location used for calculations
longitude: (string) Longitude of the location used for calculations

📅 Historical Data Access

Access historical data by adding the date parameter:

Ultra plan: Access up to 2 years of historical data
Mega plan: Access up to 27 years of historical data
Precise calculations based on specific coordinates worldwide

GET /astrology

Get complete astrological data including natal chart, planetary positions, house cusps, aspects, and element/modality breakdown.

Query Parameters:

Parameter	Type	Required	Description	Plan Availability
lat	number	optional	Latitude for location-specific data	Same as /advanced endpoint
lon	number	optional	Longitude for location-specific data	Same as /advanced endpoint
timestamp	number	optional	Unix timestamp for historical/future data	Same as /advanced endpoint

Example Request:

GET /astrology?lat=51.5074&lon=-0.1278

Example Response:

{
  "meta": {
    "timestamp": "2026-01-14T09:39:27Z",
    "location": {
      "lat": 51.5074,
      "lon": -0.1278,
      "timezone": "Europe/London",
      "house_system": "equal"
    },
    "coordinate_system": "tropical",
    "zodiac": "tropical",
    "ephemeris": "pyephem",
    "reference_frame": "geocentric",
    "longitude_type": "apparent",
    "equinox": "date",
    "orb_rules": {
      "conjunction": 8,
      "sextile": 6,
      "square": 8,
      "trine": 8,
      "opposition": 8
    }
  },
  "points": {
    "sun": {
      "lon": 293.86,
      "lat": 0,
      "house": 11
    },
    "moon": {
      "lon": 244.62,
      "lat": -5.1,
      "house": 10
    },
    "mercury": {
      "lon": 289.3,
      "lat": -1.74,
      "house": 11
    },
    "venus": {
      "lon": 295.71,
      "lat": -0.96,
      "house": 11
    },
    "mars": {
      "lon": 292.66,
      "lat": -0.96,
      "house": 11
    },
    "jupiter": {
      "lon": 109.19,
      "lat": 0.27,
      "house": 5
    },
    "saturn": {
      "lon": 356.72,
      "lat": -2.22,
      "house": 1
    },
    "uranus": {
      "lon": 57.28,
      "lat": -0.2,
      "house": 3
    },
    "neptune": {
      "lon": 359.36,
      "lat": -1.32,
      "house": 1
    },
    "pluto": {
      "lon": 302.77,
      "lat": -3.78,
      "house": 11
    }
  },
  "houses": {
    "cusps": [
      333.67,
      3.67,
      33.67,
      63.67,
      93.67,
      123.67,
      153.67,
      183.67,
      213.67,
      243.67,
      273.67,
      303.67
    ],
    "ascendant": 333.67,
    "midheaven": 258.61
  },
  "aspects": [
    {
      "p1": "sun",
      "p2": "mercury",
      "type": "conjunction",
      "orb": 4.56
    },
    {
      "p1": "sun",
      "p2": "venus",
      "type": "conjunction",
      "orb": 1.84
    },
    {
      "p1": "sun",
      "p2": "mars",
      "type": "conjunction",
      "orb": 1.21
    },
    {
      "p1": "sun",
      "p2": "jupiter",
      "type": "opposition",
      "orb": 4.67
    },
    {
      "p1": "sun",
      "p2": "saturn",
      "type": "sextile",
      "orb": 2.85
    },
    {
      "p1": "sun",
      "p2": "uranus",
      "type": "trine",
      "orb": 3.41
    },
    {
      "p1": "sun",
      "p2": "neptune",
      "type": "sextile",
      "orb": 5.49
    },
    {
      "p1": "moon",
      "p2": "saturn",
      "type": "trine",
      "orb": 7.91
    },
    {
      "p1": "moon",
      "p2": "uranus",
      "type": "opposition",
      "orb": 7.35
    },
    {
      "p1": "moon",
      "p2": "neptune",
      "type": "trine",
      "orb": 5.27
    },
    {
      "p1": "moon",
      "p2": "pluto",
      "type": "sextile",
      "orb": 1.85
    },
    {
      "p1": "mercury",
      "p2": "venus",
      "type": "conjunction",
      "orb": 6.4
    },
    {
      "p1": "mercury",
      "p2": "mars",
      "type": "conjunction",
      "orb": 3.35
    },
    {
      "p1": "mercury",
      "p2": "jupiter",
      "type": "opposition",
      "orb": 0.11
    },
    {
      "p1": "mercury",
      "p2": "uranus",
      "type": "trine",
      "orb": 7.97
    },
    {
      "p1": "venus",
      "p2": "mars",
      "type": "conjunction",
      "orb": 3.05
    },
    {
      "p1": "venus",
      "p2": "jupiter",
      "type": "opposition",
      "orb": 6.51
    },
    {
      "p1": "venus",
      "p2": "saturn",
      "type": "sextile",
      "orb": 1.01
    },
    {
      "p1": "venus",
      "p2": "uranus",
      "type": "trine",
      "orb": 1.57
    },
    {
      "p1": "venus",
      "p2": "neptune",
      "type": "sextile",
      "orb": 3.65
    },
    {
      "p1": "venus",
      "p2": "pluto",
      "type": "conjunction",
      "orb": 7.07
    },
    {
      "p1": "mars",
      "p2": "jupiter",
      "type": "opposition",
      "orb": 3.46
    },
    {
      "p1": "mars",
      "p2": "saturn",
      "type": "sextile",
      "orb": 4.06
    },
    {
      "p1": "mars",
      "p2": "uranus",
      "type": "trine",
      "orb": 4.62
    },
    {
      "p1": "jupiter",
      "p2": "saturn",
      "type": "trine",
      "orb": 7.53
    },
    {
      "p1": "saturn",
      "p2": "uranus",
      "type": "sextile",
      "orb": 0.56
    },
    {
      "p1": "saturn",
      "p2": "neptune",
      "type": "conjunction",
      "orb": 2.64
    },
    {
      "p1": "uranus",
      "p2": "neptune",
      "type": "sextile",
      "orb": 2.08
    },
    {
      "p1": "uranus",
      "p2": "pluto",
      "type": "trine",
      "orb": 5.5
    },
    {
      "p1": "neptune",
      "p2": "pluto",
      "type": "sextile",
      "orb": 3.41
    }
  ]
}

docs.apiDocs.fieldDescriptions

timestamp: (integer) UNIX timestamp of the calculation
datestamp: (string) Date and time in UTC format
location: (object) Location and timezone metadata:
- latitude: (number) Latitude used for calculations
- longitude: (number) Longitude used for calculations
- timezone: (string) IANA timezone identifier
- using_defaults: (boolean) Whether default coordinates were used
plan: (string) Current API plan level
astrology: (object) Astrology data payload:
- natal_chart: (object) Sun, moon, ascendant, and midheaven data
- planets: (object) Planetary positions with sign, house, altitude/azimuth, visibility
- houses: (object) House cusps, elements, and modalities
- aspects: (array) Planetary aspect list with angle/orb
- elements: (object) Element distribution counts
- modalities: (object) Modality distribution counts

GET /calendar

All Plans

Get a complete lunar calendar for a specified year in HTML or Markdown table format. The calendar displays months as rows and days 1-31 as columns with moon phase emojis. Uses exact phase dates calculated in the local timezone for accurate day-perfect phase assignments.

Query Parameters:

Parameter	Type	Required	Description	Plan Availability
lat	number	optional	Latitude for location-specific data (default: 51.5074 - London)	Basic: Default only Pro: ✅ (coarse) Ultra: ✅ (fine) Mega: ✅ (fine)
lon	number	optional	Longitude for location-specific data (default: -0.1278 - London)	Basic: Default only Pro: ✅ (coarse) Ultra: ✅ (fine) Mega: ✅ (fine)
year	integer	optional	Year to generate calendar for (default: current year). Must be between 1900 and 2100.	All Plans ✅
format	string	optional	Response format - 'html' or 'markdown' (default: markdown)	All Plans ✅

📅 Calendar Features

Day-Perfect Accuracy: Uses exact phase transition times in local timezone to ensure phases appear on the correct day
Complete Year View: Always returns all 12 months for the specified year
Multiple Formats: Available in HTML (for web integration) or Markdown (for documentation)
Location-Aware: Calendar phases are calculated for the specified location's timezone

Response: HTML Format:

HTML Format

Returns a complete HTML page with a styled table containing moon phase emojis, perfect for web integration or direct display.

Markdown Format

Returns a markdown-formatted table with moon phase emojis, ideal for documentation, README files, or markdown-based systems.

Example Request:

GET /calendar?year=2026&format=markdown
GET /calendar?year=2026&format=html&lat=51.5074&lon=-0.1278

Example Response (Markdown):

| Month | 1 | 2 | ... | 31 |
|---|---|---|---|---|
| January | 🌒 | 🌓 | ... | 🌕 |

GET /phase

All Plans

Get current moon phase information. Returns JSON format with detailed phase data.

Query Parameters:

Parameter	Type	Required	Description	Plan Availability
lat	number	optional	Latitude for location-specific data	Same as /advanced endpoint
lon	number	optional	Longitude for location-specific data	Same as /advanced endpoint

Response:

GET /emoji

All Plans

Get current moon phase as an emoji. Returns plain text (not JSON), perfect for social media integration.

Query Parameters:

Parameter	Type	Required	Description	Plan Availability
lat	number	optional	Latitude for location-specific data	Same as /advanced endpoint
lon	number	optional	Longitude for location-specific data	Same as /advanced endpoint

Response:

🌒

Code Examples

Practical examples of integrating Moon API in different programming languages and frameworks.

const options = {
  method: 'GET',
  url: 'https://moon-phase.p.rapidapi.com/advanced',
  headers: {
    'X-RapidAPI-Key': 'your-api-key',
    'X-RapidAPI-Host': 'moon-phase.p.rapidapi.com'
  }
};

try {
  const response = await axios.request(options);
  console.log(response.data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://moon-phase.p.rapidapi.com/advanced"

headers = {
    "X-RapidAPI-Key": "your-api-key",
    "X-RapidAPI-Host": "moon-phase.p.rapidapi.com"
}

response = requests.get(url, headers=headers)
print(response.json())

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://moon-phase.p.rapidapi.com/advanced",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-RapidAPI-Key: your-api-key",
        "X-RapidAPI-Host: moon-phase.p.rapidapi.com"
    ]
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

#include <ESP8266WiFi.h>
#include <ESP8266HTTPClient.h>
#include <ArduinoJson.h>

const char* ssid = "YourWiFiSSID";
const char* password = "YourWiFiPassword";
const char* host = "moon-phase.p.rapidapi.com";
const char* apiKey = "your-api-key";

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
}

void loop() {
  if (WiFi.status() == WL_CONNECTED) {
    HTTPClient http;
    WiFiClient client;
    
    http.begin(client, "http://moon-phase.p.rapidapi.com/basic");
    http.addHeader("X-RapidAPI-Key", apiKey);
    http.addHeader("X-RapidAPI-Host", "moon-phase.p.rapidapi.com");
    
    int httpCode = http.GET();
    if (httpCode > 0) {
      String payload = http.getString();
      Serial.println(payload);
      
      StaticJsonDocument<200> doc;
      deserializeJson(doc, payload);
      
      const char* phase = doc["phase_name"];
      Serial.println(phase);
    }
    
    http.end();
    delay(60000); // Wait 1 minute before next request
  }
}

curl --request GET \
  --url https://moon-phase.p.rapidapi.com/advanced \
  --header 'X-RapidAPI-Key: your-api-key' \
  --header 'X-RapidAPI-Host: moon-phase.p.rapidapi.com'

Features

Feature	Basic	Pro	Ultra	Mega
All Endpoints	✅	✅	✅	✅
Requests/Month	500	1,000	10,000	100,000
Requests/Second	1	5	100	1000
Custom Coordinates	Default only	✅ (coarse)	✅ (fine)	✅ (fine)
Historical/Future Data	✅ (30 days)	✅ (1 year)	✅ (2 years)	✅ (27 years)
Eclipse Data	❌	❌	✅	✅
Response Time	Standard	Fast	Faster	Fastest
Support	Community	Email	Priority Email	24/7 Priority

Best Practices

🚀 Performance

Cache responses when possible
Use the simplest endpoint for your needs
Implement rate limiting on your side
Handle API responses asynchronously

🛡️ Security

Keep your API key secure
Use HTTPS for all requests
Implement proper error handling
Validate user inputs before sending

📈 Optimization

Use appropriate coordinate precision
Batch requests when possible
Implement proper error handling
Monitor your API usage

Troubleshooting

Having issues with the API? Check out our FAQ for common questions and answers.

Common Error Messages

❌ Invalid Number Format (422 Error)

Problem: You're using a comma instead of a period for decimal numbers.

Example Error:

{
  "error": "Validation Error",
  "message": "One or more parameters are invalid...",
  "details": [{
    "field": "query -> lat",
    "message": "Invalid number format for 'query -> lat'. Use a period (.) as decimal separator, not a comma.",
    "received": "-34,6"
  }]
}

Solution: Replace commas with periods in decimal numbers:

❌ ?lat=-34,6&lon=-58,5
✅ ?lat=-34.6&lon=-58.5

Why this happens: Some regions use commas as decimal separators, but the API requires standard decimal notation with periods.

❌ Invalid Parameter Type (422 Error)

Problem: A parameter has the wrong data type.

Common Issues:

Latitude/Longitude: Must be numbers between -90 to 90 (lat) and -180 to 180 (lon)
Timestamp: Must be a Unix timestamp (integer), not a date string
Year: Must be an integer between 1900 and 2100

Examples:

❌ ?lat=abc&lon=123 → lat must be a number
❌ ?lat=91&lon=0 → lat must be between -90 and 90
❌ ?timestamp=2024-01-01 → timestamp must be Unix timestamp (integer)
✅ ?lat=40.7128&lon=-74.0060
✅ ?timestamp=1704067200

❌ Missing Required Parameter (422 Error)

Problem: A required parameter is missing from your request.

Solution: Check the endpoint documentation to see which parameters are required. Most parameters in our API are optional, but if you see this error, verify you're using the correct parameter names.

❌ Date Range Out of Bounds (400 Error)

Problem: The requested date is outside your plan's allowed range.

Solution: Check your plan's limits:

FREE: Current time only (no historical/future data)
BASIC: ±30 days from today
PRO: ±1 year from today
ULTRA: ±2 years from today
MEGA: ±27 years from today

HTTP Status Codes

Code	Meaning	Common Causes	How to Fix
`400`	Bad Request	Date out of range, invalid format	Check parameter values and plan limits
`401`	Unauthorized	Missing or invalid API key	Verify your API key is included in headers
`403`	Forbidden	Rate limit exceeded, plan restrictions	Check your rate limits and plan features
`404`	Not Found	Invalid endpoint URL	Verify the endpoint path is correct
`422`	Validation Error	Invalid parameter format or type	Check error details for specific field issues
`500`	Server Error	Internal server issue	Retry the request. If it persists, contact support

Error Response Format

All validation errors (422) follow this structure:

{
  "error": "Validation Error",
  "message": "One or more parameters are invalid. Please check the details below.",
  "details": [
    {
      "field": "query -> lat",
      "message": "Invalid number format for 'query -> lat'. Use a period (.) as decimal separator, not a comma.",
      "received": "-34,6"
    },
    {
      "field": "query -> lon",
      "message": "Invalid number format for 'query -> lon'. Use a period (.) as decimal separator, not a comma.",
      "received": "-58,5"
    }
  ]
}

Tips for Avoiding Errors

Use periods for decimals: Always use . not , for decimal numbers
Check coordinate ranges: Latitude: -90 to 90, Longitude: -180 to 180
Use Unix timestamps: For historical data, use integer Unix timestamps, not date strings
Verify plan limits: Check your plan's date range and feature restrictions
URL encode parameters: Special characters in URLs should be properly encoded

If you're still experiencing issues, please contact our support team.

Moon API Documentation - Real-time Lunar Data API

Moon API Documentation

Overview

Getting Started

Authentication

Endpoints

GET /basic

Query Parameters:

Response:

docs.apiDocs.fieldDescriptions

GET /advanced

Query Parameters:

Response:

docs.apiDocs.fieldDescriptions

📅 Historical Data Access

GET /astrology

Query Parameters:

Example Request:

Example Response:

docs.apiDocs.fieldDescriptions

GET /calendar

Query Parameters:

📅 Calendar Features

Response: HTML Format:

HTML Format

Markdown Format

Example Request:

Example Response (Markdown):

GET /phase

Query Parameters:

Response:

GET /emoji

Query Parameters:

Response:

Code Examples

Features

Best Practices

🚀 Performance

🛡️ Security

📈 Optimization

Troubleshooting

Common Error Messages

❌ Invalid Number Format (422 Error)

❌ Invalid Parameter Type (422 Error)

❌ Missing Required Parameter (422 Error)

❌ Date Range Out of Bounds (400 Error)

HTTP Status Codes

Error Response Format

Tips for Avoiding Errors