Moon Phases

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

Returns tropical lunar phases (new moon, full moon, quarters, and intermediate phases) with status annotation and cycle grouping. Six query types including cycles for full lunation tracking.

Authentication

Required.

Request body

Field	Type	Required	Description
`query_type`	string	No	`current`, `date`, `range`, `month`, `year`, `cycles`.
`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	Lunation cycles for `cycles` query. Default `1`, max `24`.
`phase_filter`	string	No	Filter: `new_moon`, `full_moon`, `first_quarter`, `last_quarter`, etc. Cannot combine with `cycles`.
`group_by_cycle`	boolean	No	Group phases into lunation cycles. Default `false`.

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`).
`datetime_utc`	string	Exact phase time in UTC.
`datetime_local`	string	Converted to requested timezone.
`moon_sign`	string	Tropical sign of the Moon.
`sun_sign`	string	Tropical sign of the Sun.
`status`	string	`past`, `current`, or `upcoming`.
`days_from_now`	number	Signed days from now.

Cycle fields (when grouped)

When group_by_cycle: true or query_type: cycles, phases are wrapped in cycle objects with cycle_number, partial, new_moon, full_moon, duration_days, phase_count, and phases array.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/transit/western/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/western/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/western/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/western/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/western/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/western/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/western/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/western/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/western/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": "tropical",
      "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": "Gemini",
        "sun_sign": "Gemini",
        "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",
        "status": "past",
        "days_from_now": -1.8
      }
    ]
  },
  "meta": { "endpoint": "/api/v3/transit/western/moon-phases", "version": "3.0", "zodiac": "tropical" }
}