Ephemeris

Endpoint POST https://starsapi.com/api/v3/transit/vedic/ephemeris

Returns daily sidereal planetary positions for every day in a given month, computed at 00:00 UTC. Includes all classical planets plus outer planets (Uranus, Neptune, Pluto), and provides both true and mean node positions for Rahu and Ketu in every row.

The timezone parameter only adjusts the displayed local time label — the underlying data is always computed at midnight UTC for consistency.

Authentication

Required. See basic → Authentication.

Request body

Field	Type	Required	Description
`month`	integer	Yes	Calendar month, 1–12.
`year`	integer	Yes	4-digit year.
`timezone`	string	No	IANA timezone for local time label. Default `UTC`.
`ayanamsa`	string	No	Default `lahiri`.
`planet`	string	No	`all` (default), `traditional` (7 classical + nodes), or specific planet name (e.g. `Jupiter`, `Rahu`).

Response shape

query

Echo of resolved parameters.

Each day in `ephemeris`

Field	Type	Description
`date`	string	`YYYY-MM-DD`.
`weekday`	string	3-letter weekday (e.g. `Mon`).
`time_utc`	string	Always `00:00`.
`time_local`	string	Local time equivalent of midnight UTC.

Planet entries per day

Field	Type	Description
`name`	string	Planet name. Nodes use `Rahu (True)`, `Rahu (Mean)`, etc.
`symbol`	string	Unicode glyph (e.g. `☉`, `☽`, `☊`).
`longitude`	number	Sidereal ecliptic longitude (0–360).
`sign`	string	Zodiac sign.
`degree_in_sign`	number	Degree within sign (0–30).
`degree_dms`	string	DMS format.
`is_retrograde`	boolean	Retrograde flag.

Node handling

Unlike snapshot endpoints where node_type selects one variant, the ephemeris returns both true and mean nodes in every row, keyed as rahu_true, rahu_mean, ketu_true, ketu_mean. This lets you display either (or both) without a second API call.

Use cases

Panchang tables — daily planetary position reference for almanac/calendar apps.
Ephemeris page — traditional tabular ephemeris display.
Transit trend analysis — plot a planet’s daily longitude over a month.
Node comparison — compare true vs mean Rahu/Ketu positions side by side.

Errors

HTTP	Code	Cause
400	`VALIDATION_ERROR`	Month or year out of range.
400	`INVALID_PLANET`	Unrecognised planet filter.
400	`INVALID_TIMEZONE`	Numeric or non-IANA timezone.

Plus standard auth errors.

const response = await fetch(
  'https://starsapi.com/api/v3/transit/vedic/ephemeris',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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/ephemeris',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'month': 6,
        'year': 2026,
        'timezone': 'Asia/Kolkata'
    }
)
result = response.json()

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

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

$ch = curl_init('https://starsapi.com/api/v3/transit/vedic/ephemeris');
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/ephemeris'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      '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/ephemeris"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "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 = """
    {
        "month": 6,
        "year": 2026,
        "timezone": "Asia/Kolkata"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/transit/vedic/ephemeris")
        .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{}{
        "month": 6,
        "year": 2026,
        "timezone": "Asia/Kolkata",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/transit/vedic/ephemeris",
        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/ephemeris')
payload = {
  '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",
      "ayanamsa": "lahiri",
      "planet": "all",
      "computed_at": "00:00 UTC daily",
      "nodes": "both true and mean (rahu_true/mean, ketu_true/mean)"
    },
    "days": 30,
    "ephemeris": [
      {
        "date": "2026-06-01",
        "weekday": "Mon",
        "time_utc": "00:00",
        "time_local": "05:30",
        "planets": {
          "Sun": {
            "name": "Sun",
            "symbol": "☉",
            "longitude": 46.1234,
            "sign": "Taurus",
            "degree_in_sign": 16.1234,
            "degree_dms": "16°7'24\"",
            "is_retrograde": false
          },
          "rahu_true": {
            "name": "Rahu (True)",
            "symbol": "☊",
            "longitude": 352.8901,
            "sign": "Pisces",
            "degree_in_sign": 22.8901,
            "degree_dms": "22°53'24\"",
            "is_retrograde": true
          },
          "rahu_mean": {
            "name": "Rahu (Mean)",
            "symbol": "☊",
            "longitude": 353.1245,
            "sign": "Pisces",
            "degree_in_sign": 23.1245,
            "degree_dms": "23°7'28\"",
            "is_retrograde": true
          }
        }
      }
    ]
  },
  "meta": {
    "endpoint": "/api/v3/transit/vedic/ephemeris",
    "version": "3.0"
  }
}