Astrology API Quick Start: TypeScript & Python in 5 Minutes

🕓 Recorded 2026-04-14, updated 2026-05-09. TS / Python / PHP SDKs are now live on public registries — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Details in changelog.

You want to calculate a natal chart from code. Here’s the fastest path — under 5 minutes from nothing to working JSON.

Step 1: Get an API key (30 seconds)

In the dashboard, click “Create key” → “Production” → copy it. Keys look like aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR.

Tip: There are also aw_test_ sandbox keys that don’t consume credits. Use them for development.

Step 2: Install the SDK

TypeScript

npm install @astroway/sdk

Python

pip install astroway

Both SDKs cover all 705 endpoints with typed requests and responses.

Step 3: Your first natal chart

TypeScript

import { Astroway } from '@astroway/sdk';

const client = new Astroway({
  apiKey: process.env.ASTROWAY_API_KEY!,
});

const chart = await client.chart({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,      // UTC+3 for Kyiv summer
  latitude: 50.4501,
  longitude: 30.5234,
  houseSystem: 'P',       // Placidus
});

console.log(`Sun: ${chart.planets[0].sign} at ${chart.planets[0].longitude}°`);
console.log(`ASC: ${chart.houses.ascendant}°`);
console.log(`Aspects: ${chart.aspects.length}`);

Run it:

ASTROWAY_API_KEY=aw_live_... npx tsx chart.ts

Python

from astroway import Astroway

client = Astroway(api_key="aw_live_your_key_here")

chart = client.chart(
    date="1990-07-14",
    time="14:30:00",
    timezone_offset=3,
    latitude=50.4501,
    longitude=30.5234,
    house_system="P",
)

print(f"Sun: {chart['planets'][0]['sign']} at {chart['planets'][0]['longitude']}°")
print(f"ASC: {chart['houses']['ascendant']}°")
print(f"Aspects: {len(chart['aspects'])}")

Run it:

ASTROWAY_API_KEY=aw_live_... python3 chart.py

Understanding the response

You get back a JSON object with four main parts:

planets

Array of 12 objects (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, Chiron):

{
  "name": "Sun",
  "longitude": 111.87,      // ecliptic longitude in degrees
  "latitude": 0.0,
  "speed": 0.955,           // degrees per day (negative = retrograde)
  "sign": "cancer",
  "signIndex": 3,
  "house": 10,
  "retrograde": false
}

houses

House cusps (12 of them), plus ascendant and MC:

{
  "system": "P",
  "cusps": [12.34, 43.21, ...],   // 12 values
  "ascendant": 12.34,
  "mc": 280.12
}

aspects

Array of aspects between planets:

{
  "planet1": "Sun",
  "planet2": "Moon",
  "type": "sextile",        // conjunction, opposition, trine, square, sextile, quincunx
  "orb": 1.36,              // deviation from exact in degrees
  "applying": true
}

chartSect

"diurnal" (Sun above horizon at birth) or "nocturnal" (below). Used in classical astrology.

Next steps

What to try next:

Synastry — compatibility between two people:

const synastry = await client.synastry({
  chart1: { date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
  chart2: { date: '1992-03-22', time: '09:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
});
console.log(`Compatibility score: ${synastry.compatibility.score}/100`);

Current transits on a natal chart:

const transits = await client.transits({
  // birth data
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
  // transit date
  transitDate: '2026-04-14',
});

Daily horoscope generated from real transits:

const horoscope = await client.horoscopeDaily({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
});
console.log(horoscope.text);

Full Human Design chart:

const hd = await client.humanDesign({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
});
console.log(`${hd.type} — ${hd.strategy} — Profile ${hd.profile}`);

Credit costs

Natal chart (/chart): 20 credits
Synastry: 50 credits
Transits: 50 credits
Daily horoscope: 20 credits
Human Design: 50 credits

Free plan: 10,000 credits/month = 500 natal charts, or 200 synastries, or mixed workload.

Error handling

Every response includes credit headers:

X-Credits-Used: 20
X-Credits-Remaining: 4980
X-Credits-Reset: 2026-05-01T00:00:00Z

When credits run out you get 402 Payment Required. When rate limit hits (Free: 10 req/min), 429 Too Many Requests with Retry-After header.

SDK throws typed errors you can catch:

try {
  const chart = await client.chart({ ... });
} catch (err) {
  if (err.code === 'credits_exhausted') {
    console.log('Upgrade plan or wait for reset');
  } else if (err.code === 'rate_limit_exceeded') {
    console.log(`Retry in ${err.retryAfter} seconds`);
  }
}

That’s it

You now have:

A working API key
SDK installed
First natal chart
Enough patterns to add synastry, transits, horoscopes

Next reading:

Full getting started guide — more detail
Example: Natal chart — deeper walkthrough
API reference — all 705 endpoints

AstroWay team

Engineering team at AstroWay API. We ship Swiss Ephemeris on a clean REST surface and write about the dull parts that turn out to matter.

// build with this

Same Swiss Ephemeris as Solar Fire — but in 4 lines of code.

Free key, no card. 5,000 calls/month before you pay anything.

Get an API key → Read the docs

Astrology API Quick Start: TypeScript & Python in 5 Minutes

Step 1: Get an API key (30 seconds)

Step 2: Install the SDK

TypeScript

Python

Step 3: Your first natal chart

TypeScript

Python

Understanding the response

planets

houses

aspects

chartSect

Next steps

Credit costs

Error handling

That’s it

Same Swiss Ephemeris as Solar Fire — but in 4 lines of code.

More from the blog view all posts →

How to Build an Astrology App: A Complete Developer Guide

Human Design API: Build HD Apps with 12 Endpoints

Add Astrology to Your AI Agent with MCP