Planet in Sign

Endpoint POST https://starsapi.com/api/v3/western/predictions/planet-in-sign

Computes the tropical natal chart and returns a prewritten interpretation for each of 13 bodies in its sign — Sun through Pluto, plus Chiron, Lilith (Mean Black Moon), and Part of Fortune. The 156 combinations cover the canonical Western sign readings. Outer planets (Uranus, Neptune, Pluto) are written in generational framing because they linger years per sign; Chiron and Lilith carry their own thematic voice (wound/healing and suppressed power respectively); inner planets carry the fully personal voice.

For house-based readings use planet-in-house. For aspect interpretations use aspects.

Content tiers — the content tier is derived from your API key, not from the request. Internal keys receive premium content (richer voice, deeper detail); public keys receive canonical. Future white-label partners will receive their own branded text via partner_{slug}. When the requested language has no entry, the response falls back to English automatically.

Authentication

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

Request body

Field	Type	Required	Description
`year`	integer	Yes	Birth year.
`month`	integer	Yes	Birth month, 1–12.
`day`	integer	Yes	Birth day.
`hour`	integer	Yes	Birth hour, 0–23 (24-hour).
`minute`	integer	Yes	Birth minute, 0–59.
`second`	integer	No	Birth second, default 0.
`latitude`	number	Yes	Decimal degrees.
`longitude`	number	Yes	Decimal degrees.
`timezone`	string	Yes	IANA timezone (e.g. `Asia/Kolkata`).
`language`	string	No	Language code. Supported: `en`, `es` (Spanish), `fr` (French), `pt` (Portuguese), `it` (Italian), `de` (German), `ru` (Russian). Default `en`. Falls back to English when the requested language has no entry.
`house_system`	string	No	Any of 23 supported systems. Default `placidus`. See house systems.
`node_type`	string	No	One of `true`, `mean`, `both`. Default `true`.

Response shape

Field	Type	Description
`house_system`	string	The house system actually applied (default Placidus).
`language`	string	The language requested.
`predictions[]`	array	One entry per body (Sun…Pluto, Chiron, Lilith, Fortune). Each carries `planet`, `house`, `sign`, `retrograde`, and `prediction` (`title` and `text`). When the combination has no entry in any tier or language, `prediction` is `null`.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Bad calendar date.
400	`INVALID_PARAM`	Bad `language` value (must be one of the seven supported codes).
400	`INVALID_TIMEZONE`	Non-IANA timezone.
400	`INVALID_COORDINATE`	Lat/lon out of range.
405	`METHOD_NOT_ALLOWED`	Non-POST request.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/predictions/planet-in-sign" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Priya",
        "gender": "female",
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "language": "en"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/predictions/planet-in-sign',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Priya',
      gender: 'female',
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata',
      language: 'en'
    })
  }
);
const result = await response.json();

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

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/western/predictions/planet-in-sign',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'name': 'Priya',
        'gender': 'female',
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata',
        'language': 'en'
    }
)
result = response.json()

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

<?php
$payload = [
    'name' => 'Priya',
    'gender' => 'female',
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
    'language' => 'en',
];

$ch = curl_init('https://starsapi.com/api/v3/western/predictions/planet-in-sign');
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/western/predictions/planet-in-sign'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'name': 'Priya',
      'gender': 'female',
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
      'language': 'en',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/predictions/planet-in-sign"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "name": "Priya",
            "gender": "female",
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata",
            "language": "en"
        }
        """.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 = """
    {
        "name": "Priya",
        "gender": "female",
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "language": "en"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/predictions/planet-in-sign")
        .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{}{
        "name": "Priya",
        "gender": "female",
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "language": "en",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/predictions/planet-in-sign",
        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/western/predictions/planet-in-sign')
payload = {
  'name' => 'Priya',
  'gender' => 'female',
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'language' => 'en'
}

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": {
    "language": "en",
    "predictions": [
      {
        "planet": "Sun",
        "house": 9,
        "sign": "Taurus",
        "retrograde": false,
        "prediction": {
          "title": "Sun in Taurus",
          "text": "You are built like the season you were born in \u2014 fertile, steady, quietly unstoppable. Patience is your superpower\u2026"
        }
      },
      {
        "planet": "Mars",
        "house": 6,
        "sign": "Pisces",
        "retrograde": false,
        "prediction": {
          "title": "Mars in Pisces",
          "text": "Your drive moves like current under calm water\u2026"
        }
      }
    ]
  },
  "meta": { "endpoint": "/api/v3/western/predictions/planet-in-sign", "version": "3.0" }
}