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. Supply an optional natal block to get the house each phase falls in for a given birth chart, plus tight hits to natal planets.

Authentication

Required.

Request body

Field	Type	Required	Description
`query_type`	string	No	`live`, `current`, `date`, `range`, `month`, `year`, `cycles`. 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	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 on any query type. Default `false`.
`natal`	object	No	Birth data for chart personalisation (see below). When present, every phase gains a `natal` block.

`query_type: live`

Returns the Moon's state at this exact instant (not the next phase event): current illumination, phase, sign, and the upcoming New and Full Moons. Shaped as { live, next_phase, next_new_moon, next_full_moon } rather than a phases array. Each of these carries a natal block when natal is supplied.

The `natal` object

Field	Type	Required	Description
`year`, `month`, `day`	integer	Yes	Birth date.
`hour`, `minute`	integer	Yes	Birth time (24h, local).
`second`	integer	No	Default `0`.
`latitude`, `longitude`	number	Yes	Signed decimals (N/E positive).
`timezone`	string	Yes	IANA timezone of birth.
`house_system`	string	No	Default `placidus`.

Response shape

Phase fields

Field	Type	Description
`phase`	string	Display name (e.g. `New Moon`).
`phase_key`	string	Machine key (e.g. `new_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`, `sun`	object	`{ sign, degree_in_sign, longitude }`.
`status`	string	`past`, `current`, or `upcoming`.
`days_from_now`	number	Signed days from now.
`natal`	object	Present only when `natal` supplied: `{ house, house_theme, hits[] }`. Each hit is `{ natal_planet, aspect, orb }` (conjunction/opposition within 3° to natal planets, Ascendant or Midheaven).

Cycle fields (when grouped)

When group_by_cycle: true or query_type: cycles, phases are wrapped in lunation cycle objects. The new_moon/full_moon/lunation_* anchors are UTC; for display use the datetime_local of the phases themselves, or the ready-made status_label.

Field	Type	Description
`cycle_number`	integer	1-based index within this response.
`partial`	boolean	`true` when the first cycle does not begin on a new moon (possible when grouping a `month`/`range`/`year` query).
`new_moon`, `full_moon`	string	UTC instants of this lunation's principal events.
`phase_count`	integer	Phase events in this cycle (normally 8).
`duration_days`	number	Span from the first to the last marked phase (≈26d). Not the lunation length — see below.
`lunation_start`, `lunation_end`	string	UTC bounds of the true lunation: this new moon → the next new moon.
`lunation_days`	number	True lunation length (≈29.5d).
`status`	string	`past`, `current`, or `upcoming`.
`lunation_day`	integer	Which day of the lunation today is. Set only when `status: current`; otherwise `null`.
`next_new_moon`	string	UTC instant that closes this lunation.
`days_to_next_new`	number	Days until that next new moon.
`status_label`	string	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	The phase objects for this cycle.

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 the next new moon.

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.

# 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": "range",
        "from_date": "2026-07-10",
        "to_date": "2026-09-10",
        "timezone": "Asia/Kolkata",
        "group_by_cycle": true,
        "natal": {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "latitude": 28.6139,
            "longitude": 77.209,
            "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: 'range',
      from_date: '2026-07-10',
      to_date: '2026-09-10',
      timezone: 'Asia/Kolkata',
      group_by_cycle: true,
      natal: 'Array'
    })
  }
);
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': 'range',
        'from_date': '2026-07-10',
        'to_date': '2026-09-10',
        'timezone': 'Asia/Kolkata',
        'group_by_cycle': True,
        'natal': 'Array'
    }
)
result = response.json()

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

<?php
$payload = [
    'query_type' => 'range',
    'from_date' => '2026-07-10',
    'to_date' => '2026-09-10',
    'timezone' => 'Asia/Kolkata',
    'group_by_cycle' => true,
    'natal' => 'Array',
];

$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': 'range',
      'from_date': '2026-07-10',
      'to_date': '2026-09-10',
      'timezone': 'Asia/Kolkata',
      'group_by_cycle': true,
      'natal': 'Array',
    }),
  );
  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": "range",
            "from_date": "2026-07-10",
            "to_date": "2026-09-10",
            "timezone": "Asia/Kolkata",
            "group_by_cycle": true,
            "natal": {
                "year": 1990,
                "month": 5,
                "day": 20,
                "hour": 14,
                "minute": 30,
                "latitude": 28.6139,
                "longitude": 77.209,
                "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": "range",
        "from_date": "2026-07-10",
        "to_date": "2026-09-10",
        "timezone": "Asia/Kolkata",
        "group_by_cycle": true,
        "natal": {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "latitude": 28.6139,
            "longitude": 77.209,
            "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": "range",
        "from_date": "2026-07-10",
        "to_date": "2026-09-10",
        "timezone": "Asia/Kolkata",
        "group_by_cycle": true,
        "natal": "Array",
    })

    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' => 'range',
  'from_date' => '2026-07-10',
  'to_date' => '2026-09-10',
  'timezone' => 'Asia/Kolkata',
  'group_by_cycle' => true,
  'natal' => 'Array'
}

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": "range",
      "from": "2026-07-10", "to": "2026-09-10",
      "timezone": "Asia/Kolkata", "zodiac": "tropical",
      "phase_filter": null, "natal": true, "group_by_cycle": true
    },
    "count": 18,
    "cycle_count": 4,
    "cycles": [
      {
        "cycle_number": 2,
        "partial": false,
        "new_moon": "2026-07-14 09:43:37",
        "full_moon": "2026-07-29 14:35:43",
        "duration_days": 26,
        "phase_count": 8,
        "lunation_start": "2026-07-14 09:43:37",
        "lunation_end": "2026-08-12 17:36:45",
        "lunation_days": 29.3,
        "status": "upcoming",
        "lunation_day": null,
        "next_new_moon": "2026-08-12 17:36:45",
        "days_to_next_new": 31.6,
        "status_label": "Begins in 2d",
        "phases": [
          {
            "phase": "New Moon",
            "phase_key": "new_moon",
            "phase_emoji": "\ud83c\udf11",
            "datetime_utc": "2026-07-14 09:43:37",
            "datetime_local": "2026-07-14 15:13:37",
            "illumination_pct": 0,
            "moon": { "sign": "Cancer", "degree_in_sign": "21:59:11", "longitude": 111.99 },
            "sun":  { "sign": "Cancer", "degree_in_sign": "21:59:11", "longitude": 111.99 },
            "status": "upcoming",
            "days_from_now": 3.4,
            "natal": {
              "house": 11,
              "house_theme": "Friends, networks, aspirations",
              "hits": [ { "natal_planet": "Mars", "aspect": "opposition", "orb": 2.51 } ]
            }
          }
        ]
      }
    ]
  },
  "meta": { "endpoint": "/api/v3/transit/western/moon-phases", "version": "3.0", "zodiac": "tropical" }
}