Natal Chart

Endpoint POST https://starsapi.com/api/v3/western/natal/chart

Overview

Computes the natal chart and returns a signed URL to a PNG wheel chart image. The URL is valid for 24 hours and can be embedded in <img> tags, shared with users, or opened directly in a browser. No API key is needed to load the image URL itself — it’s protected by HMAC signature.

This endpoint does not return planet positions, aspects, or house cusps in the response body. Use planets, aspects, and houses for data. This endpoint is purely for the chart image.

The chart image can be customized with branding: native’s name, birth info, place (on separate line), and a branding/attribution line in the top-left corner, plus optional center text replacing the default watermark.

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 (1800–2400).
`month`	integer	Yes	Birth month (1–12).
`day`	integer	Yes	Birth day.
`hour`	integer	Yes	Birth hour (0–23).
`minute`	integer	Yes	Birth minute (0–59).
`second`	integer	No	Default `0`.
`latitude`	number	Yes	Decimal degrees (−90 to 90).
`longitude`	number	Yes	Decimal degrees (−180 to 180).
`timezone`	string	Yes	IANA timezone.
`house_system`	string	No	Default `placidus`. See house systems.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.
`include_minor_aspects`	boolean	No	Show minor aspects on the chart. Default `true`.
`name`	string	No	Native’s name. Displayed in chart top-left corner.
`place`	string	No	Birth place. Displayed on a separate line below date/time.
`branding`	string	No	Attribution line (e.g. `"Powered by MyApp.com"`). Displayed below birth info.
`center_text`	string	No	Text to display in chart center. Replaces default watermark. Send empty string for no center text.

Branding options

The chart image renders an optional information block in the top-left corner:

Priya                              ← name (bold, 26px)
May 20, 1990, 14:30 IST           ← auto-generated from birth data (20px)
New Delhi                          ← place on separate line (18px)
Powered by MyAstroApp.com         ← branding attribution (18px, lighter)

Auto-generated birth info: if you send name and/or place but no explicit birth_info, the chart auto-formats the date/time line as May 20, 1990, 14:30 IST using the timezone abbreviation from the birth data. DST is correctly resolved.

If no branding fields are sent, the chart renders clean with no corner text and no center watermark.

Response shape

`data.chart_url`

Signed HTTPS URL to the PNG chart image. Valid for 24 hours. The URL uses HMAC-SHA256 authentication — no API key needed to load the image. Suitable for embedding in <img> tags, sharing via links, or downloading.

Image specs: 1100×1100 PNG, RGBA, typically 250–300 KB. Aspect lines color-coded by type (red = challenging, green = harmonious, etc.).

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_DATE`	Invalid calendar date or year outside range.
400	`INVALID_TIME`	Hour/minute/second outside valid range.
400	`INVALID_TIMEZONE`	Not a valid IANA identifier.
400	`INVALID_COORDINATE`	Latitude or longitude out of range.
400	`INVALID_PARAM`	Invalid `house_system`.
500	`EPHEMERIS_ERROR`	Swiss Ephemeris computation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/natal/chart" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "name": "Priya",
        "place": "New Delhi",
        "branding": "Powered by MyAstroApp.com",
        "center_text": "MyAstroApp"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/natal/chart',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata',
      house_system: 'placidus',
      node_type: 'true',
      name: 'Priya',
      place: 'New Delhi',
      branding: 'Powered by MyAstroApp.com',
      center_text: 'MyAstroApp'
    })
  }
);
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/natal/chart',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata',
        'house_system': 'placidus',
        'node_type': 'true',
        'name': 'Priya',
        'place': 'New Delhi',
        'branding': 'Powered by MyAstroApp.com',
        'center_text': 'MyAstroApp'
    }
)
result = response.json()

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

<?php
$payload = [
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
    'house_system' => 'placidus',
    'node_type' => 'true',
    'name' => 'Priya',
    'place' => 'New Delhi',
    'branding' => 'Powered by MyAstroApp.com',
    'center_text' => 'MyAstroApp',
];

$ch = curl_init('https://starsapi.com/api/v3/western/natal/chart');
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/natal/chart'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
      'house_system': 'placidus',
      'node_type': 'true',
      'name': 'Priya',
      'place': 'New Delhi',
      'branding': 'Powered by MyAstroApp.com',
      'center_text': 'MyAstroApp',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/natal/chart"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata",
            "house_system": "placidus",
            "node_type": "true",
            "name": "Priya",
            "place": "New Delhi",
            "branding": "Powered by MyAstroApp.com",
            "center_text": "MyAstroApp"
        }
        """.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 = """
    {
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "name": "Priya",
        "place": "New Delhi",
        "branding": "Powered by MyAstroApp.com",
        "center_text": "MyAstroApp"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/natal/chart")
        .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{}{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "name": "Priya",
        "place": "New Delhi",
        "branding": "Powered by MyAstroApp.com",
        "center_text": "MyAstroApp",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/chart",
        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/natal/chart')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'house_system' => 'placidus',
  'node_type' => 'true',
  'name' => 'Priya',
  'place' => 'New Delhi',
  'branding' => 'Powered by MyAstroApp.com',
  'center_text' => 'MyAstroApp'
}

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": {
    "chart_url": "https://starsapi.com/api/v3/western/natal/chart-image?key=9b88187a...&expires=1781760879&token=90b1fe09..."
  },
  "meta": {
    "endpoint": "/api/v3/western/natal/chart",
    "version": "3.0",
    "response_time_ms": 4,
    "timestamp": "2026-06-17T11:07:49+05:30",
    "credits_remaining": 197320,
    "request_id": "8bc101957be46a35"
  }
}