SDKs & quickstart

One API, two official clients. Use JavaScript / TypeScript or Python on your server, and build the interface your users need.

Choose the language your backend uses; you do not need both packages. Both 0.5.0 clients expose 78 calculation methods plus Tarot, symbolic readings and supplemental Vedic systems. They call the same hosted API; installing a package does not run the calculation engine locally.

Create a server-side key

  1. Create an account and open API Keys.
  2. For this first calculation, select astro:birth-chart. Add only the other scopes your application needs.
  3. Save the one-time secret as COSMICEPHEMERIS_KEY in your backend's private environment or secret manager.

Never paste the key into a browser bundle, mobile app, shared notebook, source file or public repository. Client SDKs are for your backend—not your visitors' browsers.

Node.js / TypeScript

Requires Node.js 22 or newer. The ESM package includes TypeScript declarations and has no runtime dependencies. Save the JavaScript example as an .mjs file, or use an ESM project.

npm install cosmicephemeris@0.5.0
import { CosmicEphemeris, CosmicEphemerisError } from "cosmicephemeris";

// Reads COSMICEPHEMERIS_KEY from your server environment.
const api = new CosmicEphemeris();
try {
  const result = await api.birthChart({
    date: "2000-01-01", time: "12:00", timezone: "UTC", lat: 0, lon: 0
  });
  // Render or store result.chart in your application.
} catch (error) {
  if (error instanceof CosmicEphemerisError) {
    console.error(error.code, error.status, error.retryAfter);
  } else { throw error; }
}

Node package and reference on npm. Run your saved example with node example.mjs after configuring the environment.

Python

Requires Python 3.10 or newer. This is a synchronous, typed client with no required runtime dependencies. Install in your project's virtual environment.

python -m pip install cosmicephemeris-client==0.5.0
from cosmicephemeris_client import (
    CosmicEphemerisClient, HTTPError, RequestTimeoutError
)

# Reads COSMICEPHEMERIS_KEY from your server environment.
api = CosmicEphemerisClient()
try:
    result = api.birth_chart({
        "date": "2000-01-01", "time": "12:00",
        "timezone": "UTC", "lat": 0, "lon": 0
    })
    # Render or store result["chart"] in your application.
except HTTPError as error:
    print(error.status, error.retry_after)
except RequestTimeoutError:
    print("Deadline exceeded; admitted work may still use quota.")

Python package and reference on PyPI. Run your saved example with python example.py.

Add Tarot or readings

Use astro:tarot for Tarot and astro:symbolic-reading for readings. Both methods return the complete reading object, including sections, evidence, disclosures and content version. Your application renders and stores it.

const tarot = await api.tarot({locale: "en", options: {
  mode: "draw", spread: "three", theme: "general", reversals: true
}});
const reading = await api.symbolicReading({
  kind: "birth", locale: "en", tradition: "western",
  birth: {date: "2000-01-01", time: "12:00", timezone: "UTC", lat: 0, lon: 0}
});
tarot = api.tarot({"locale": "en", "options": {
    "mode": "draw", "spread": "three", "theme": "general", "reversals": True
}})
reading = api.symbolic_reading({
    "kind": "birth", "locale": "en", "tradition": "western",
    "birth": {"date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 0, "lon": 0}
})

Each example call is billable under your standard quota once admitted, including failed calculations. Draws may vary; do not automatically retry. These methods do not create saved account history, export account PDFs, support batch jobs or request signed receipts. In Python, keep request_receipts=False (the default).

For Vedic systems, use vedicSystems in Node or vedic_systems in Python with astro:vedic-systems. See the supplemental guide and exact input schema.

Handle errors and usage deliberately

  • No automatic retries: a timeout does not prove a request was unprocessed. Admitted attempts can consume quota even when they fail.
  • Deadlines: defaults vary by route. Use the operation-specific examples for longer calculations; Node accepts per-call timeoutMs, Python accepts client timeout in seconds.
  • HTTP failures: inspect the sanitized SDK error and status. Check credentials for 401, scope/plan restrictions for 403, and quota or concurrency restrictions for 429. Do not log credentials or private birth data.
  • Response envelopes: birth charts use result.chart in Node or result["chart"] in Python. Other operations have different wrappers; SDKs preserve them.

Choose your next step

  • All 78 calculation examples — exact inputs and sample responses.
  • Historical dates — explicit BCE/CE calendar and UT1 objects; do not turn BCE inputs into JavaScript Date or Python datetime.
  • Jobs and webhooks — separate HTTP workflows for supported calculation routes.
  • MCP — agent-host integration rather than a language SDK.