GetBirthChart

Developer platform

Build astrology into your product

Build natal charts, sign tools, aspects and synastry with the calculation stack behind GetBirthChart.

Get API keyView documentation
TypeScript
import { GetBirthChart } from "@getbirthchart/sdk";

const client = new GetBirthChart({
  apiKey: process.env.GETBIRTHCHART_API_KEY,
  baseUrl: "https://getbirthchart.com/api",
});

const chart = await client.calculateBirthChart({
  date: "1990-01-15",
  time: "12:00",
  place: "New York, NY",
  latitude: 40.7128,
  longitude: -74.006,
  timezone: "America/New_York",
});

Technical trust

Ephemeris-backed

Planetary positions use the backend ephemeris through pyswisseph.

Unknown-time safe

Time-dependent fields are omitted when a reliable birth time is missing.

Typed interfaces

The TypeScript SDK returns structured data and typed errors.

Transparent methodology

Rules, sources, validation and release metadata are documented.

SDKs and integrations

Use the interface that fits your stack.

JavaScript / TypeScript

Available

A typed ESM client for natal charts, signs, positions, aspects and synastry.

npm install @getbirthchart/sdk

Version 0.1.0 is published on npm.

GitHubnpmQuick start

Python

Available

Use the open-source calculation engine directly for structured natal chart facts.

pip install gbc-astro

Package 1.12.2. Engine 1.12.1.

PyPIGitHubSoftware page

MCP Server

In development

A planned agent interface for structured astrology calculations and explicit uncertainty.

The v0.1 tool surface is being designed. No public server or registry entry exists yet.

calculate_birth_chartget_planet_positionsget_big_threeget_moon_signget_rising_signcalculate_aspectscalculate_synastry

WordPress

Coming soon

A planned integration for embedding GetBirthChart-powered calculators in WordPress.

The plugin is not published yet. Installation and shortcode behavior are not final.

What you can build

Start with a calculation surface, then shape the product around it.

Birth chart experiences

Natal chart calculators and chart-driven applications.

Moon and Rising tools

Focused sign calculators and onboarding flows.

Relationship products

Synastry and compatibility experiences built from two charts.

AI astrology agents

Assistants grounded in structured calculation data through an API or MCP.

Astrology content systems

Calculation-backed pages and workflows with clear editorial limits.

Research and internal tools

Work directly with positions, aspects and engine metadata.

Core capabilities

The matrix reflects the current state of each developer surface.

GetBirthChart capability availability by integration
CapabilityRESTTypeScriptPythonMCPWordPress
Birth chartAvailableAvailableAvailablePlanned-
Planet positionsAvailableAvailableAvailablePlanned-
Sun signAvailableAvailablePartialPlanned-
Moon signAvailableAvailablePartialPlanned-
Rising signAvailableAvailableAvailablePlanned-
Big ThreeAvailableAvailableAvailablePlanned-
AspectsAvailableAvailableAvailablePlanned-
SynastryAvailableAvailablePartialPlanned-
Unknown-time handlingAvailableAvailableAvailablePlanned-
Engine metadataAvailableAvailableAvailablePlanned-

Preview means the contract or source exists, but public access is not available yet. Partial means the capability is exposed through a broader chart or engine surface.

Unknown birth time is handled explicitly

The SDK does not turn missing information into a guessed time.

Without a reliable time, the engine does not guess an Ascendant or houses. Time-sensitive fields are omitted, and Moon uncertainty remains explicit when the available date cannot establish one sign.

Birth chart without birth timeWhy birth time matters
TypeScript
const chart = await client.calculateBirthChart({
  date: "1990-01-15",
  place: "New York, NY",
  latitude: 40.7128,
  longitude: -74.006,
  timezone: "America/New_York",
  unknownTime: true,
});

console.log(chart.birthTimeKnown); // false
console.log(chart.ascendant); // undefined
console.log(chart.houses); // undefined

Known birth time

Bodies, angles, houses and aspects can be returned when the input is complete.

Unknown birth time

Bodies remain available. Ascendant and houses are omitted rather than guessed.

Know what the calculation is based on

Authoritative reference pages keep the implementation inspectable.

Methodology

Calculation pipeline, zodiac, houses and the boundary between facts and interpretation.

Read reference

Data Sources

Ephemeris calculations, IANA timezone rules and geographic coordinate data.

Read reference

Validation

Deterministic fixtures, regression cases, boundaries and reproducibility checks.

Read reference

Engine and Releases

Current engine namespaces, schema changes and public material release history.

Read reference

Open-source foundations

Inspect the calculation engine, SDK source and release provenance.

gbc-astro

The installable Python package for the GetBirthChart calculation engine.

PyPIGitHub

@getbirthchart/sdk

The TypeScript client source, tests and release workflow.

GitHubnpm package

Engine provenance

The package release is archived and citable under the engine project license.

ZenodoDOIAGPL-3.0-only

Engine information

These values come from the web app's pinned engine contract and calculation-core constants.

Engine
gbc-astro 1.12.1
Package
gbc-astro 1.12.2
Schema
1.3.0
Zodiac
Tropical by default
Houses
Placidus by default
License
AGPL-3.0-only

An API philosophy for calculation

Structured

Return explicit calculation data rather than opaque generated prose.

Predictable

Use typed interfaces, documented errors and explicit uncertainty.

Transparent

Document the methodology, sources and engine versions behind output.

Quick start

Copy the shortest useful example for your stack.

ts
import { GetBirthChart } from "@getbirthchart/sdk";

const client = new GetBirthChart({
  apiKey: process.env.GETBIRTHCHART_API_KEY,
  baseUrl: "https://getbirthchart.com/api",
});

const chart = await client.calculateBirthChart({
  date: "1990-01-15",
  time: "12:00",
  place: "New York, NY",
  latitude: 40.7128,
  longitude: -74.006,
  timezone: "America/New_York",
});

Start building

Create a developer API key, keep it on your server, and call the versioned chart endpoints with structured JSON responses.

Get API key