{"id":"015b549b-b27f-4d9f-ac8a-7567073cdef3","slug":"moon-phase-api","kind":"mcp","name":"moon-phase-api","summary":"Moon phase API. Current phase, illumination, age, sign, degree plus upcoming phases and calendar by year and month. Working code samples, one key.","owner":"RoxyAPI","repoUrl":"https://github.com/RoxyAPI/moon-phase-api","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-31T05:50:55.000Z","addedAt":"2026-10-21T04:38:59.244Z","logoUrl":"https://avatars.githubusercontent.com/u/185915295?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity","developer-tools","cloud-infra"],"tags":["astrology-api","full-moon","illumination","lunar-calendar","moon-phase","new-moon","wellness-api","moon-phase-api"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T02:19:02.399Z","sample":false,"url":"https://conduits.dev/tools/moon-phase-api","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"[![Moon Phase API](banner.png)](https://roxyapi.com/products/astrology-api)\n\n# Moon Phase API\n\n> Current moon phase with illumination, lunar age, zodiac sign, and degree, plus upcoming phases and a full lunar calendar. One key covers 18+ spiritual domains. MCP-first, no local setup required.\n\n[![Get API Key](https://img.shields.io/badge/Get_API_Key-RoxyAPI-14b8a6?style=for-the-badge&logo=key&logoColor=white)](https://roxyapi.com/pricing)\n[![Try Live](https://img.shields.io/badge/Try_API_Live-Free_in_browser-22c55e?style=for-the-badge&logo=swagger&logoColor=white)](https://roxyapi.com/api-reference)\n[![Methodology](https://img.shields.io/badge/Methodology-NASA_JPL_verified-f59e0b?style=for-the-badge&logo=nasa&logoColor=white)](https://roxyapi.com/methodology)\n[![MCP Server](https://img.shields.io/badge/MCP_Server-Streamable_HTTP-8b5cf6?style=for-the-badge&logo=anthropic&logoColor=white)](https://roxyapi.com/docs/mcp)\n[![SDK](https://img.shields.io/badge/SDK-TypeScript_+_Python_+_PHP_+_C%23_+_Go_+_WordPress-3b82f6?style=for-the-badge&logo=npm&logoColor=white)](https://roxyapi.com/docs/sdk)\n\n## What is Moon Phase API\n\nThe RoxyAPI moon phase endpoint returns the current lunar phase with illumination percentage, lunar age in days since the new moon, the tropical zodiac sign the Moon occupies, its degree, and distance from Earth. Phase names cover the full lunar cycle from New Moon through Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, and Waning Crescent. Each call can also return a moon phase meaning with energy direction and keywords, ideal for moon tracking apps, lunar calendars, and astrology widgets. One RoxyAPI subscription covers 18+ spiritual domains, all positions powered by Roxy Ephemeris, verified against NASA JPL Horizons.\n\n## Why this API\n\n| Property | Value |\n|----------|-------|\n| Coverage | 18+ spiritual domains in one subscription |\n| Calculation | Roxy Ephemeris, verified against NASA JPL Horizons |\n| MCP server | `https://roxyapi.com/mcp/astrology` (Streamable HTTP, no local setup) |\n| SDKs | TypeScript on npm `@roxyapi/sdk`, Python on PyPI `roxy-sdk`, PHP on Packagist `roxyapi/sdk`, C# on NuGet `RoxyApi.Sdk`, Go `github.com/RoxyAPI/sdk-go`, WordPress plugin `roxyapi` |\n| Pricing | One key, flat per call, from $39/mo |\n| Licensing | Personal and commercial use, including closed source apps. No AGPL or GPL entanglement. [Full terms](https://roxyapi.com/policy/license) |\n| Last verified | 2026-Q3 |\n\n## Quick start\n\n1. Get a key at [roxyapi.com/pricing](https://roxyapi.com/pricing)\n2. Pick a language below\n3. Copy the snippet, run, ship\n\n### cURL\n\n```bash\n# Current moon phase. Defaults to today at noon UTC.\ncurl -s \"https://roxyapi.com/api/v2/astrology/moon-phase/current\" \\\n  -H \"X-API-Key: $ROXY_API_KEY\"\n\n# Specific date with a timezone offset for a localized lunar calendar day\ncurl -s \"https://roxyapi.com/api/v2/astrology/moon-phase/current?date=2026-05-31&timezone=5.5\" \\\n  -H \"X-API-Key: $ROXY_API_KEY\"\n```\n\n### Python\n\n```python\nimport os\nfrom roxy_sdk import create_roxy\n\nroxy = create_roxy(os.environ[\"ROXY_API_KEY\"])\n\n# Current moon phase. All query params optional, defaults to today at noon UTC.\nmoon = roxy.astrology.get_current_moon_phase()\n\nprint(moon[\"phase\"])          # Full Moon\nprint(moon[\"illumination\"])   # 99.8\nprint(moon[\"age\"])            # 14.89\nprint(moon[\"sign\"])           # Sagittarius\nprint(moon[\"degree\"])         # 11.54\nprint(moon[\"meaning\"][\"keywords\"])  # ['harvest', 'illumination', 'clarity', ...]\n```\n\n### JavaScript (Node)\n\n```js\nimport { createRoxy } from '@roxyapi/sdk';\n\nconst roxy = createRoxy(process.env.ROXY_API_KEY);\n\n// Current moon phase with illumination, lunar age, zodiac sign, and degree\nconst { data, error } = await roxy.astrology.getCurrentMoonPhase();\n\nif (error) throw new Error(error.error);\n\nconsole.log('Phase:', data.phase);                // Full Moon\nconsole.log('Illumination:', data.illumination);  // 99.8\nconsole.log('Lunar age:', data.age);              // 14.89\nconsole.log('Sign:', data.sign);                  // Sagittarius\nconsole.log('Degree:', data.degree);              // 11.54\n```\n\n### TypeScript\n\n```ts\nimport { createRoxy } from '@roxyapi/sdk';\n\nconst roxy = createRoxy(process.env.ROXY_API_KEY!);\n\n// Moon phase: returns phase, illumination, age, sign, degree, distance, and phase meaning\nconst { data, error } = await roxy.astrology.getCurrentMoonPhase({\n  query: { date: '2026-05-31', timezone: 5.5 },\n});\n\nif (error) throw new Error(error.error);\n\nconsole.log('Phase:', data.phase);\nconsole.log('Illumination:', data.illumination, '%');\nconsole.log('Lunar age:', data.age, 'days');\nconsole.log('Sign:', data.sign);\nconsole.log('Keywords:', data.meaning?.keywords);\n```\n\n## Request schema\n\nAll parameters are query string and optional.\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `date` | string (query) | no | Date in YYYY-MM-DD format. Defaults to today if omitted. |\n| `time` | string (query) | no | Time in 24-hour HH:MM:SS format. Defaults to 12:00:00 (noon). Moon moves ~13 degrees per day so time affects phase precision. |\n| `timezone` | number or string (query) | no | Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\"). IANA resolved to the DST-correct offset for the given date. Defaults to 0 (UTC). |\n| `lang` | string (query) | no | Interpretation language. Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. |\n\n## Response shape\n\n```json\n{\n  \"date\": \"2026-05-31\",\n  \"phase\": \"Full Moon\",\n  \"illumination\": 99.8,\n  \"age\": 14.89,\n  \"sign\": \"Sagittarius\",\n  \"degree\": 11.54,\n  \"distance\": 406195,\n  \"meaning\": {\n    \"name\": \"Full Moon\",\n    \"symbol\": \"🌕\",\n    \"description\": \"The full moon is also known as the harvest moon, and as the name suggests, it is a time to receive the gifts of your past intentions and your current cycle. From this period, the moon will go from waxing to waning, signaling a journey to look inward instead of out. Emotions and awareness are heightened, and clarity about what serves you becomes undeniable.\",\n    \"keywords\": [\"harvest\", \"illumination\", \"clarity\", \"culmination\", \"celebration\"],\n    \"energy\": \"full\",\n    \"illumination\": \"100% (Fully Illuminated)\"\n  }\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `date` | string | Date of this moon phase calculation (YYYY-MM-DD). |\n| `phase` | string | Current lunar phase name. One of: New Moon, Waxing Crescent Moon, First Quarter Moon, Waxing Gibbous Moon, Full Moon, Waning Gibbous Moon, Last Quarter Moon, Waning Crescent Moon. |\n| `illumination` | number | Moon illumination percentage (0-100). 0 = New Moon, 100 = Full Moon. |\n| `age` | number | Lunar age in days since the last New Moon. Full lunation cycle is ~29.53 days. |\n| `sign` | string | Tropical zodiac sign the Moon currently occupies. |\n| `degree` | number | Degree of the Moon within its current zodiac sign (0-29.999). |\n| `distance` | number | Distance from Earth to the Moon in kilometers. |\n| `meaning` | object | Moon phase meaning and astrological interpretation. Includes energy direction, keywords, and guidance for this lunar phase. Optional. |\n| `meaning.name` | string | Moon phase display name. |\n| `meaning.symbol` | string | Moon phase emoji symbol. |\n| `meaning.description` | string | Astrological interpretation of this lunar phase and its influence on activities, emotions, and intentions. |\n| `meaning.keywords` | array | Key themes and activities aligned with this moon phase. |\n| `meaning.energy` | string | Lunar energy direction: waxing (building), waning (releasing), new (beginning), or full (culmination). |\n| `meaning.illumination` | string | Illumination range description for this phase. |\n\n## Common use cases\n\n| Use case | Endpoint flow |\n|----------|---------------|\n| Moon tracking app home screen | GET `/astrology/moon-phase/current`, surface `phase`, `illumination`, and `meaning.symbol` |\n| Lunar calendar for a content site | GET `/astrology/moon-phase/calendar/{year}/{month}` to render every day of the month |\n| Full moon and new moon push reminders | GET `/astrology/moon-phase/upcoming` overnight, schedule local-time delivery on transition dates |\n| Gardening by moon phase tool | GET `/astrology/moon-phase/current`, branch logic on `energy` (waxing vs waning) |\n| Astrology widget with moon sign | GET `/astrology/moon-phase/current`, surface `sign` and `degree` for the Moon position |\n\n## Related endpoints in this domain\n\n- `GET /astrology/moon-phase/upcoming` (`getUpcomingMoonPhases`) - next New Moon, First Quarter, Full Moon, and Last Quarter transition dates for lunar event calendars\n- `GET /astrology/moon-phase/calendar/{year}/{month}` (`getMoonCalendar`) - complete lunar calendar with phase and illumination for every day of a month\n- `GET /astrology/horoscope/{sign}/daily` (`getDailyHoroscope`) - daily transit forecast by zodiac sign with Moon sign, Moon phase, and energy rating\n\n## Use this in your AI agent\n\nConnect Claude, GPT, Gemini, or Cursor to RoxyAPI through the remote MCP server. No Docker. No self hosting. The full MCP tool catalog for this domain is at `https://roxyapi.com/mcp/astrology`.\n\n```json\n{\n  \"mcpServers\": {\n    \"astrology\": {\n      \"url\": \"https://roxyapi.com/mcp/astrology\",\n      \"headers\": { \"X-API-Key\": \"$ROXY_API_KEY\" }\n    }\n  }\n}\n```\n\nSee [docs/mcp](https://roxyapi.com/docs/mcp) for Claude Desktop, Cursor, Windsurf, VS Code, and Claude Code setup.\n\n## For AI coding agents\n\nThis repo ships an [AGENTS.md](AGENTS.md) execution playbook. Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, and Gemini CLI will pick it up automatically. Top level overview lives at [roxyapi.com/AGENTS.md](https://roxyapi.com/AGENTS.md).\n\n## Resources\n\n- [Methodology and gold standard tests](https://roxyapi.com/methodology) verified against NASA JPL Horizons\n- [Full API reference](https://roxyapi.com/api-reference) interactive Scalar UI\n- [TypeScript SDK on npm](https://www.npmjs.com/package/@roxyapi/sdk)\n- [Python SDK on PyPI](https://pypi.org/project/roxy-sdk/)\n- [PHP SDK on Packagist](https://packagist.org/packages/roxyapi/sdk)\n- [C# SDK on NuGet](https://www.nuget.org/packages/RoxyApi.Sdk)\n- [Go SDK on pkg.go.dev](https://pkg.go.dev/github.com/RoxyAPI/sdk-go)\n- [WordPress plugin](https://wordpress.org/plugins/roxyapi/)\n- [llms.txt](https://roxyapi.com/llms.txt) full LLM citation index\n- [Top level AGENTS.md](https://roxyapi.com/AGENTS.md)\n\n## Other RoxyAPI samples\n\n[![KP Astrology API](https://img.shields.io/badge/KP_Astrology_API-RoxyAPI-14b8a6?style=flat-square)](https://github.com/RoxyAPI/kp-astrology-api)\n[![Kundli API](https://img.shields.io/badge/Kundli_API-RoxyAPI-14b8a6?style=flat-square)](https://github.com/RoxyAPI/kundli-api)\n[![Daily Horoscope API](https://img.shields.io/badge/Daily_Horoscope_API-RoxyAPI-14b8a6?style=flat-square)](https://github.com/RoxyAPI/daily-horoscope-api)\n[![Panchang API](https://img.shields.io/badge/Panchang_API-RoxyAPI-14b8a6?style=flat-square)](https://github.com/RoxyAPI/panchang-api)\n[![Biorhythm API](https://img.shields.io/badge/Biorhythm_API-RoxyAPI-14b8a6?style=flat-square)](https://github.com/RoxyAPI/biorhythm-api)\n\n## License\n\nMIT for this sample repo. See [LICENSE](LICENSE).\n\n**Catalog licensing:** Personal and commercial use, including closed source proprietary apps. No AGPL or GPL entanglement. RoxyAPI APIs and SDKs are safe to embed in commercial products. Full terms at [roxyapi.com/policy/license](https://roxyapi.com/policy/license).\n\n## Contact\n\n- Site: [roxyapi.com](https://roxyapi.com)\n- Status: [roxyapi.com/api-reference](https://roxyapi.com/api-reference)\n"}