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

Six query types are supported. The first five follow the standard calendar pattern:

`query_type`	Description
`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`).

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`).
`datetime_utc`	string	Exact phase time in UTC.
`datetime_local`	string	Converted to requested timezone.
`moon_sign`	string	Sidereal sign of the Moon at the phase.
`sun_sign`	string	Sidereal sign of the Sun.
`moon_nakshatra`	string	Moon’s nakshatra.
`moon_pada`	integer	Moon’s nakshatra pada.
`moon_nakshatra_lord`	string	Vimshottari lord.
`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 of the cycle in days.
`phase_count`	integer	Number of phases in this cycle.
`phases`	array	Phase objects (same shape as above).

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_PHASE_FILTER`	Unrecognised `phase_filter` value.
400	`INVALID_COMBINATION`	`phase_filter` used with `query_type: cycles`.

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",
        "datetime_utc": "2026-06-04 08:12:00",
        "datetime_local": "2026-06-04 13:42:00",
        "moon_sign": "Taurus",
        "sun_sign": "Taurus",
        "moon_nakshatra": "Rohini",
        "moon_pada": 2,
        "moon_nakshatra_lord": "Moon",
        "status": "past",
        "days_from_now": -16.2
      },
      {
        "phase": "Full Moon",
        "phase_key": "full_moon",
        "datetime_utc": "2026-06-18 14:35:00",
        "datetime_local": "2026-06-18 20:05:00",
        "moon_sign": "Sagittarius",
        "sun_sign": "Gemini",
        "moon_nakshatra": "Mula",
        "moon_pada": 1,
        "moon_nakshatra_lord": "Ketu",
        "status": "past",
        "days_from_now": -1.8
      }
    ]
  },
  "meta": {
    "endpoint": "/api/v3/transit/vedic/moon-phases",
    "version": "3.0"
  }
}