Moon Phases

Endpoint POST https://starsapi.com/api/v3/transit/vedic/moon-phases

Returns sidereal lunar phases — new moon, full moon, quarters, and intermediate phases. Each phase carries the exact UTC and local datetime, the Moon and Sun’s sidereal sign, nakshatra, pada, and nakshatra lord. Phases are annotated with status (past, current, upcoming) and days_from_now.

Query types

Seven query types are supported. live describes the Moon at this instant (a continuously changing state); every other type returns phase events — discrete moments when the Moon hits an exact Sun–Moon angle.

`query_type`	Description
`live`	Real-time Moon state right now — phase, illumination, sidereal sign and nakshatra — plus the next phase, next new moon and next full moon.
`current`	Next upcoming phase from today.
`date`	Phases on a specific date.
`range`	Phases within a date range.
`month`	All phases in a calendar month.
`year`	All phases in a calendar year.
`cycles`	Full lunation cycles (new moon → new moon). Returns `count` complete cycles (default 1, max 24) starting from the current lunation.

Request body

Field	Type	Required	Description
`query_type`	string	No	Default `current`.
`timezone`	string	No	IANA timezone. Default `UTC`.
`date`	string	*	Required for `date`.
`from_date`, `to_date`	string	*	Required for `range`.
`month`, `year`	integer	*	Required for `month`/`year`.
`count`	integer	No	Number of lunation cycles for `cycles` query. Default `1`, max `24`.
`phase_filter`	string	No	Show only this phase: `new_moon`, `full_moon`, `first_quarter`, `last_quarter`, `waxing_crescent`, `waxing_gibbous`, `waning_gibbous`, `waning_crescent`. Cannot be used with `cycles`.
`group_by_cycle`	boolean	No	Wrap phases into lunation cycle groups on any query type. Default `false` (always `true` for `cycles`).
`ayanamsa`	string	No	`live` only. Sidereal reference frame. Default `lahiri`. The phase-event modes always use Lahiri.
`node_type`	string	No	`live` only. `mean` or `true`. Default `mean`.

`query_type: live`

Returns the Moon’s state at this exact instant rather than the next phase event. Shaped as { live, next_phase, next_new_moon, next_full_moon } instead of a phases array. The phase instant is zodiac-neutral, so the times match the western endpoint exactly — only the reported signs differ.

{ "query_type": "live", "timezone": "Asia/Kolkata" }

Field	Type	Description
`phase`, `phase_key`, `phase_emoji`	string	Which of the eight phases the Moon is in right now.
`illumination_pct`	number	Percent of the disc lit (0 at new moon, 100 at full).
`phase_angle`	number	Moon−Sun elongation, 0–360° (0 = new, 90 = first quarter, 180 = full, 270 = last quarter).
`waxing`	boolean	`true` while the Moon is growing (elongation < 180°).
`moon`, `sun`	object	Sidereal `{ sign, degree_in_sign, longitude, nakshatra, pada, nakshatra_lord }`.

next_phase is whichever phase event comes next; next_new_moon and next_full_moon are the next principal events specifically. Each is a normal phase object.

Response shape

Phase fields

Field	Type	Description
`phase`	string	Display name (e.g. `New Moon`, `Full Moon`).
`phase_key`	string	Machine key (e.g. `new_moon`, `full_moon`).
`phase_emoji`	string	Unicode moon-phase emoji.
`datetime_utc`	string	Exact phase time in UTC.
`datetime_local`	string	Converted to requested timezone (already localised — do not append a tz label).
`illumination_pct`	number	Percent of the disc lit (0–100).
`moon`	object	Sidereal `{ sign, degree_in_sign, longitude, nakshatra, pada, nakshatra_lord }`. `degree_in_sign` is `D:M:S`.
`sun`	object	Sidereal `{ sign, degree_in_sign, longitude }`.
`status`	string	`past`, `current` (today), or `upcoming`.
`days_from_now`	number	Signed days from now (negative = past).

Cycle fields (when grouped)

When group_by_cycle is true or query_type is cycles:

Field	Type	Description
`cycle_number`	integer	Sequential cycle index.
`partial`	boolean	`true` if this cycle didn’t start with a new moon in the result set.
`new_moon`	string\|null	UTC datetime of the cycle’s new moon.
`full_moon`	string\|null	UTC datetime of the cycle’s full moon.
`duration_days`	number\|null	Span from the first to the last marked phase (≈26d). Not the lunation length — see below.
`phase_count`	integer	Number of phases in this cycle (normally 8).
`lunation_start`, `lunation_end`	string\|null	UTC bounds of the true lunation: this new moon → the next new moon.
`lunation_days`	number\|null	True lunation length (≈29.5d).
`status`	string	`past`, `current`, or `upcoming`.
`lunation_day`	integer\|null	Which day of the lunation today is. Set only when `status: current`.
`next_new_moon`	string\|null	UTC instant that closes this lunation.
`days_to_next_new`	number\|null	Days until that next new moon.
`status_label`	string\|null	Ready-to-render string — e.g. `Day 27 of 29 · next new moon in 2d`, `Begins in 2d`, `Complete`. Display this rather than composing your own.
`phases`	array	Phase objects (same shape as above).

duration_days vs lunation_days — these differ, and both are correct. duration_days (≈26d) measures only the marked phases, new moon through waning crescent. lunation_days (≈29.5d) measures the real lunar month, new moon to next new moon. After the last marked phase the Moon stays in the same lunation for roughly three more days — so a cycle whose phases are all past can still be status: current. That is not a bug: you are in the dark days before Amavasya.

The final cycle in a cycles response has no following new moon inside the slice, so its lunation_end, lunation_days, next_new_moon and days_to_next_new are null. Request a higher count if you need them.

Use cases

Panchang calendar — display Purnima, Amavasya, and tithi-related events.
Lunar phase widget — show current moon phase with nakshatra.
Fasting/vrat alerts — use phase_filter: full_moon for Purnima vrat dates.
Lunation cycle tracker — visualize complete lunar cycles with the cycles query.

Errors

HTTP	Code	Cause
400	`INVALID_QUERY_TYPE`	`query_type` not one of `live`/`current`/`date`/`range`/`month`/`year`/`cycles`.
400	`INVALID_PHASE_FILTER`	Unrecognised `phase_filter` value.
400	`INVALID_COMBINATION`	`phase_filter` used with `query_type: cycles`.
400	`INVALID_TIMEZONE`	Numeric or non-IANA timezone.
500	`COMPUTE_ERROR`	Live Moon computation failed.

Plus standard calendar endpoint errors.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/transit/vedic/moon-phases" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query_type": "month",
        "month": 6,
        "year": 2026,
        "timezone": "Asia/Kolkata"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/transit/vedic/moon-phases',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query_type: 'month',
      month: 6,
      year: 2026,
      timezone: 'Asia/Kolkata'
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/transit/vedic/moon-phases',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'query_type': 'month',
        'month': 6,
        'year': 2026,
        'timezone': 'Asia/Kolkata'
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'query_type' => 'month',
    'month' => 6,
    'year' => 2026,
    'timezone' => 'Asia/Kolkata',
];

$ch = curl_init('https://starsapi.com/api/v3/transit/vedic/moon-phases');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/transit/vedic/moon-phases'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'query_type': 'month',
      'month': 6,
      'year': 2026,
      'timezone': 'Asia/Kolkata',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/transit/vedic/moon-phases"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "query_type": "month",
            "month": 6,
            "year": 2026,
            "timezone": "Asia/Kolkata"
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "query_type": "month",
        "month": 6,
        "year": 2026,
        "timezone": "Asia/Kolkata"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/transit/vedic/moon-phases")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "query_type": "month",
        "month": 6,
        "year": 2026,
        "timezone": "Asia/Kolkata",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/transit/vedic/moon-phases",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/transit/vedic/moon-phases')
payload = {
  'query_type' => 'month',
  'month' => 6,
  'year' => 2026,
  'timezone' => 'Asia/Kolkata'
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "query": {
      "query_type": "month",
      "month": 6,
      "year": 2026,
      "timezone": "Asia/Kolkata",
      "zodiac": "sidereal",
      "phase_filter": null,
      "group_by_cycle": false
    },
    "count": 8,
    "phases": [
      {
        "phase": "New Moon",
        "phase_key": "new_moon",
        "phase_emoji": "\ud83c\udf11",
        "datetime_utc": "2026-06-15 02:54:10",
        "illumination_pct": 0,
        "moon": {
          "sign": "Taurus",
          "degree_in_sign": "29:49:24",
          "longitude": 59.8236,
          "nakshatra": "Mrigashira",
          "pada": 2,
          "nakshatra_lord": "Mars"
        },
        "sun": {
          "sign": "Taurus",
          "degree_in_sign": "29:49:24",
          "longitude": 59.8236
        },
        "datetime_local": "2026-06-15 08:24:10",
        "status": "past",
        "days_from_now": -27
      }
    ]
  },
  "meta": {
    "endpoint": "/api/v3/transit/vedic/moon-phases",
    "version": "3.0",
    "ayanamsa": { "name": "Lahiri", "value": 24.230025, "value_dms": "24\u00b013'48\"" }
  }
}