Official TypeScript SDK for the GetBirthChart astrology calculation API. The SDK is a thin HTTP client: calculation and uncertainty semantics remain owned by the backend.

Installation

npm install @getbirthchart/sdk

Quick start

The current API requires explicit coordinates and an IANA timezone. place is an optional caller-side label and is not geocoded by this API.

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

const apiKey = process.env.GETBIRTHCHART_API_KEY;
const client = new GetBirthChart(apiKey ? { apiKey } : {});
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",
});

console.log(chart.planets, chart.ascendant, chart.aspects);

The request maps directly to the gbc-astro 1.13.0 HTTP contract. Omit the calculation options to retain the legacy defaults:

Tropical · Placidus · True Node · Standard · Chiron on · Lilith off

When needed, BirthDataInput supports the public API options for houseSystem, nodeType, aspectPreset, customAspectRules, additionalPoints, zodiac, ayanamsa, fold, and altitudeM. Sidereal requests require an ayanamsa; Lahiri is the recommended product choice. Custom aspects require rules using exactAngle and orb in degrees.

Authentication and configuration

Pass the server-side API credential as apiKey. It is sent only as an Authorization: Bearer ... header to the configured baseUrl. The client does not log or persist credentials. A custom injected fetch can observe the URL, headers, API key, and body because it is controlled by the caller; it is not a security boundary.

const client = new GetBirthChart({
  ...(process.env.GETBIRTHCHART_API_KEY
    ? { apiKey: process.env.GETBIRTHCHART_API_KEY }
    : {}),
  baseUrl: "https://api.getbirthchart.com", // HTTPS staging or localhost HTTP only
  timeout: 30_000,
});

Unknown birth time

Unknown time must be explicit. Do not pass a placeholder time. The SDK sends local_time: null and does not expose backend-dependent Ascendant or houses.

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.ascendant); // undefined
console.log(chart.houses); // undefined

getRisingSign() throws BirthTimeRequiredError for unknown time. Moon results are only definite when the backend provides sufficient evidence; otherwise uncertainty.ambiguous is true.

Other operations

const bigThree = await client.getBigThree(input);
const positions = await client.getPlanetPositions(input);
const sun = await client.getSunSign(input);
const moon = await client.getMoonSign(input);
const rising = await client.getRisingSign(input);
const aspects = await client.calculateAspects(input);
const synastry = await client.calculateSynastry({ personA: input, personB: otherInput });
const composite = await client.calculateComposite({ personA: input, personB: otherInput });
const davison = await client.calculateDavison({ personA: input, personB: otherInput });

The client exposes these methods:

calculateBirthChart, getPlanetPositions, getSunSign, getMoonSign, getRisingSign, getBigThree, calculateAspects, calculateSynastry, calculateComposite, and calculateDavison.

The response types expose natal schema 1.9.0, synastry schema 1.5.0, composite schema 1.3.0, and Davison schema 1.1.0. Compatible additive fields are preserved in raw; an incompatible major schema fails closed. HTTP natal responses may omit calculationHash. The SDK does not require it, and preserves it without truncation when the server returns it.

Errors

All thrown errors extend GetBirthChartError and expose code, status, and, when supplied by the server, requestId.

import { BirthTimeRequiredError, RateLimitError } from "@getbirthchart/sdk";

try {
  await client.getRisingSign(input);
} catch (error) {
  if (error instanceof BirthTimeRequiredError) {
    // Ask for a reliable birth time.
  } else if (error instanceof RateLimitError) {
    console.log(error.retryAfter);
  }
}

Exported error types include AuthenticationError, RateLimitError, ValidationError, BirthTimeRequiredError, LocationNotFoundError, AmbiguousLocationError, TimeoutError, and ApiError.

TypeScript and runtime

The package is ESM-first, ships declaration files, uses native fetch, targets Node.js 20+, and has no runtime dependencies. A custom fetch implementation can be injected for tests or non-Node runtimes.

The types are handwritten at the response boundary and are validated against the published OpenAPI contract from the core v1.13.0 tag. The contract source is the core API model.