Moon Phase API: Track Lunar Cycles in Your App

The moon shapes tides, calendars, agriculture, and — according to a growing body of research — even human sleep. For apps in wellness, astronomy, gardening, spirituality, and health, accurate lunar data is a high-value feature. A dedicated moon phase API lets you query the exact phase, illumination, and zodiac position of the moon for any date without shipping your own astronomy library. This guide covers the lunar cycle, the GitStrology moon phase endpoint, and practical patterns for building lunar calendars, full-moon alerts, and sleep-aware features.

The Synodic Month and the Eight Phases

The moon completes a full cycle of phases — called the synodic month — in approximately 29.53 days. This is the time it takes the moon to return to the same position relative to the sun and earth as seen from earth. Over that cycle, the visible illuminated portion of the moon grows from 0% to 100% and back to 0%, passing through eight recognized phases:

• New Moon 🌑 — illumination near 0%, the moon is between earth and the sun.
• Waxing Crescent 🌒 — a sliver of light grows on the right side (in the northern hemisphere).
• First Quarter 🌓 — half illuminated, the right half visible.
• Waxing Gibbous 🌔 — more than half lit, growing toward full.
• Full Moon 🌕 — 100% illumination, the moon is opposite the sun.
• Waning Gibbous 🌖 — light begins to recede from the right.
• Last Quarter 🌗 — half illuminated, the left half visible.
• Waning Crescent 🌘 — a shrinking sliver before the next new moon.

Each phase corresponds to a specific range of the moon's age — the number of days into the current synodic cycle — and a phase angle measured in degrees from 0 to 360. The GitStrology moon phase API returns all of these values so you can render precise visualizations or drive business logic off the data.

The GitStrology Moon Phase Endpoint

Querying the moon phase is a single GET request with an optional date parameter:

GET https://api.gitstrology.dev/v1/moon-phase?date=YYYY-MM-DD

If you omit the date parameter, the API defaults to today's date in UTC. Each call costs just 1 credit, making it one of the most affordable endpoints on the platform. See the moon phase reference for the complete parameter spec. New to the API? Start with the quickstart guide to get a key.

The Response Shape

The response includes everything you need to render a moon phase widget or drive downstream logic:

curl "https://api.gitstrology.dev/v1/moon-phase?date=2026-08-03" \
  -H "X-API-Key: gs_live_xxxxx"

{
  "data": {
    "date": "2026-08-03",
    "phase": "waxing_gibbous",
    "name": "Waxing Gibbous",
    "emoji": "🌔",
    "illumination": 0.78,
    "age": 10.9,
    "phaseAngle": 133,
    "zodiacSign": "scorpio"
  },
  "credits": { "used": 1, "remaining": 99 }
}

Here is what each field means:

• phase — a machine-readable enum: new_moon, waxing_crescent, first_quarter, waxing_gibbous, full_moon, waning_gibbous, last_quarter, waning_crescent.
• name — the human-readable display name, title-cased.
• emoji — one of 🌑 🌒 🌓 🌔 🌕 🌖 🌗 🌘, ready to drop into any UI or push notification.
• illumination — a float from 0 to 1 representing the fraction of the moon's visible surface that is lit.
• age — days into the 29.53-day synodic cycle (0 to ~29.53).
• phaseAngle — the moon's elongation angle in degrees (0–360), useful for precise astronomical rendering.
• zodiacSign — the zodiac constellation the moon currently transits, one of the twelve signs.

Using the SDK

The official TypeScript SDK exposes a gs.moonPhase() method that accepts an optional date and returns the full phase object:

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY });

// Today's moon phase
const today = await gs.moonPhase();
console.log(today.data.name);        // "Waxing Gibbous"
console.log(today.data.emoji);       // "🌔"
console.log(today.data.illumination); // 0.78

// A specific date
const birthday = await gs.moonPhase({ date: "1990-03-15" });
console.log(birthday.data.name);     // "Waning Gibbous"
console.log(birthday.data.zodiacSign); // "virgo"

The SDK handles authentication, JSON parsing, and the credit envelope automatically. Each call costs 1 credit, so you can query the moon phase for every day of a year for just 365 credits — well within the free tier's monthly budget for prototyping.

Finding the Next Full Moon

A common feature request is “when is the next full moon?” Because the synodic month is 29.53 days, you can find the next full moon by iterating forward from today until the phase enum returns full_moon. Here is a helper that does exactly that:

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY! });

async function nextFullMoon(start: Date = new Date()): Promise<{ date: string; illumination: number }> {
  const cursor = new Date(start);

  // Search up to 35 days forward (a full cycle is 29.53)
  for (let i = 0; i < 35; i++) {
    const dateStr = cursor.toISOString().slice(0, 10);
    const moon = await gs.moonPhase({ date: dateStr });

    if (moon.data.phase === "full_moon") {
      return { date: dateStr, illumination: moon.data.illumination };
    }
    cursor.setDate(cursor.getDate() + 1);
  }

  throw new Error("No full moon found in the next 35 days");
}

const fullMoon = await nextFullMoon();
console.log(`Next full moon: ${fullMoon.date} (${(fullMoon.illumination * 100).toFixed(0)}% illuminated)`);

This costs at most 15–20 credits in the worst case (you stop as soon as you hit the full moon). For production apps, cache the result once computed so you do not re-scan every request.

Building a Lunar Calendar Widget

A month-long lunar calendar is a visually compelling widget for spirituality and astronomy apps. The pattern is straightforward: query the moon phase for each day of the month and render the emoji and illumination percentage in a grid.

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY! });

async function lunarCalendar(year: number, month: number) {
  const daysInMonth = new Date(year, month, 0).getDate();
  const calendar: { date: string; emoji: string; illumination: number }[] = [];

  for (let day = 1; day <= daysInMonth; day++) {
    const dateStr = `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
    const moon = await gs.moonPhase({ date: dateStr });
    calendar.push({
      date: dateStr,
      emoji: moon.data.emoji,
      illumination: moon.data.illumination,
    });
  }

  return calendar;
}

const august = await lunarCalendar(2026, 8);
august.forEach((d) => {
  console.log(`${d.date}  ${d.emoji}  ${(d.illumination * 100).toFixed(0)}%`);
});

A full 31-day month costs 31 credits. On the Pro plan (10,000 credits/month), you can serve roughly 320 full month-calendars before hitting your limit. For higher volume, precompute the calendar once per month and cache the JSON server-side — the moon phase for a given date never changes, so the data is infinitely cacheable.

The Zodiac Sign Field

The zodiacSign field tells you which zodiac constellation the moon is transiting on the given date. The moon changes signs roughly every 2.5 days, making this a fast-moving signal compared to sun signs. Astrology apps can use this to surface “moon in Scorpio” style insights, and pairing it with the moon's phase adds depth — a full moon in Aries carries different energy than a new moon in Aries. Valid sign values are: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, and pisces.

Pairing Moon Phase with Sleep Forecasts

If you are building a health or sleep app, the moon phase is only half the story. GitStrology also offers a dedicated /v2/lunar/sleep-forecast endpoint that translates lunar phase data into predicted sleep disruption metrics — sleep latency, deep-sleep reduction, and melatonin change — based on peer-reviewed research. That endpoint is covered in depth in our lunar sleep science guide, which walks through the Cajochen and Casiraghi studies behind the model. For most apps, a clean pattern is to display the moon phase emoji as a lightweight visual, and layer in the sleep forecast for users who want deeper insight.

Caching Strategy

Moon phase data is deterministic: the phase for a given date is fixed forever. This makes it the ideal candidate for aggressive caching. Once you query a date, store the result indefinitely. A simple in-memory cache or a database table keyed by date string eliminates repeated credit consumption entirely:

const cache = new Map<string, any>();

async function cachedMoonPhase(date: string) {
  if (cache.has(date)) return cache.get(date);
  const result = await gs.moonPhase({ date });
  cache.set(date, result);
  return result;
}

With this pattern, your effective cost per unique date drops to 1 credit, amortized across every request that ever touches that date. For an app with thousands of users all viewing the current moon phase, you pay 1 credit per day, not 1 credit per user.

Practical Use Cases

Moon phase data powers features across many app categories. Here are concrete patterns teams are shipping today:

• Astronomy and stargazing apps — surface the moon phase so users know when a new moon offers the darkest skies for deep-sky observation. A waxing crescent near first quarter is ideal for lunar crater viewing.
• Gardening and farming apps — traditional planting calendars tie sowing and harvesting to lunar phases. Use the phase enum to drive planting recommendations.
• Spirituality and manifestation apps — new moon intention-setting and full moon release rituals are core features. Trigger push notifications on the exact phase transition.
• Fishing and hunting apps — solunar tables predict animal activity based on moon phase and position. The phaseAngle and age fields give you the raw data to build solunar activity scores.
• Photography apps — landscape photographers chase the golden hour and the full moon rise. Combine moon phase data with your location logic to alert users when a full moon rises near sunset.

Key Takeaways

• The synodic month lasts approximately 29.53 days and contains eight phases: New Moon 🌑, Waxing Crescent 🌒, First Quarter 🌓, Waxing Gibbous 🌔, Full Moon 🌕, Waning Gibbous 🌖, Last Quarter 🌗, and Waning Crescent 🌘.
• Query the GitStrology endpoint at GET /v1/moon-phase?date=YYYY-MM-DD — it returns phase, name, emoji, illumination (0–1), age, phaseAngle, and zodiacSign.
• The SDK method gs.moonPhase() accepts an optional date and costs just 1 credit per call.
• Find the next full moon by iterating forward up to 35 days and checking for the full_moon phase enum.
• Moon phase data is deterministic and infinitely cacheable — cache by date to reduce your effective cost to near zero.
• For sleep and health apps, layer the /v2/lunar/sleep-forecast endpoint on top, detailed in our lunar sleep science post.
• Get started with the quickstart guide, reference the moon phase docs, and review pricing to plan your credit budget.

Ready to track the moon? Grab your API key, follow the quickstart, and query your first moon phase today.