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.2.0 is published on npm.

GitHubnpmQuick start

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 chartAvailableAvailableAvailableAvailableAvailable
Planet positionsAvailableAvailableAvailableAvailable-
Sun signAvailableAvailablePartialAvailablePartial
Moon signAvailableAvailablePartialAvailableAvailable
Rising signAvailableAvailableAvailableAvailableAvailable
Big ThreeAvailableAvailableAvailableAvailableAvailable
AspectsAvailableAvailableAvailableAvailable-
SynastryAvailableAvailablePartialAvailable-
Unknown-time handlingAvailableAvailableAvailableAvailableAvailable
Engine metadataAvailableAvailableAvailableAvailable-

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.

MCP tools: calculate_birth_chart, get_planet_positions, get_big_three, get_moon_sign, get_rising_sign, calculate_aspects, calculate_synastry. Resources: getbirthchart://methodology, getbirthchart://data-sources, getbirthchart://engine-info.

Unknown birth time is handled explicitly

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

Without a reliable time, the engine's unknownTimeAssessment is authoritative: it 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.

ZenodoDOIVersion DOIAGPL-3.0-only

Engine information

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

Pinned engine
gbc-astro 1.13.0
Package
gbc-astro 1.13.0
Python
>=3.12
Natal schema
1.9.0
Synastry schema
1.5.0
Composite schema
1.3.0
Davison schema
1.1.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",
});

Calculation examples

These snippets exercise the versioned Python core. Engine/API capabilities are labeled separately from settings exposed in the public web calculator.

The public calculator defaults to Tropical, Placidus, True Node, Standard aspects and Chiron enabled.

Python
from gbc_astro import calculate_chart

chart = calculate_chart(
    date="1992-11-03",
    time="14:35",
    latitude=21.0285,
    longitude=105.8542,
    timezone="Asia/Ho_Chi_Minh",
)

print(chart.meta.house_system)  # placidus
print(chart.meta.node_type)     # true

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