gbc-astro

Overview

gbc-astro computes astrology chart data from a local date/time, geographic coordinates, IANA timezone and calculation profile. It is separate from the GetBirthChart website: accounts, payments, page rendering and interpretation text do not live in the package.

The canonical source is the gbc-astro GitHub repository (opens in a new tab). The installable package is published on PyPI (opens in a new tab) and the cited release is archived on Zenodo (opens in a new tab).

Capabilities

The public package documents natal positions, tropical zodiac signs, houses, Ascendant, Midheaven, aspects, lunar nodes, Chiron, retrograde state and derived points when geometry allows. The broader `AstrologyEngine` also exposes relationship charts, transits and returns through separate surfaces.

The package accepts coordinates rather than a city name. The website's place search and timezone selection happen before the calculation request.

Architecture

GetBirthChart follows this boundary: birth details → website place/timezone normalization → `gbc-astro` calculation → canonical chart schema → evidence selection → optional AI interpretation. The package returns structured facts; it does not generate reading prose.

Installation

The library requires Python 3.12 or newer. The base install includes the `pyswisseph` binding, while the optional `api` extra adds FastAPI and uvicorn for the HTTP adapter.

pip install gbc-astro
# Optional HTTP adapter
pip install "gbc-astro[api]"

Minimal example

This example uses the public `calculate_chart` API documented in the package README. The timezone is required and coordinates are geographic degrees, not a place name.

from gbc_astro import calculate_chart

chart = calculate_chart(
    date="1990-05-15",
    time="09:30",
    latitude=51.5074,
    longitude=-0.1278,
    timezone="Europe/London",
    house_system="placidus",
)

print(chart.bodies["sun"].sign)
print(chart.angles["ascendant"].longitude)

Version and dependencies

Package/distribution version: 1.12.2. Calculation-engine version: 1.12.1. Natal chart schema: 1.3.0. The web application is pinned to engine release v1.12.1.

The package requires `pyswisseph>=2.10.3.2`. Swiss Ephemeris `.se1` files are not included in the PyPI package and must be provisioned separately. The optional validation extra includes Skyfield, jplephem and NumPy; the optional API extra includes FastAPI and uvicorn.

License

The package is licensed under AGPL-3.0-only (opens in a new tab). Swiss Ephemeris and its data files have separate upstream licensing and redistribution terms; see the engine's third-party notices and the upstream Swiss Ephemeris information (opens in a new tab). This page is descriptive and is not legal advice.

Validation and source

Read the Calculation Validation page and the public golden-test documentation (opens in a new tab). The package's source repository (opens in a new tab), PyPI distribution (opens in a new tab), Zenodo archive (opens in a new tab) and DOI (opens in a new tab) are the canonical external references.

Used by GetBirthChart

The web app consumes the pinned v1.12.1 calculation contract and records the returned chart as schema 1.3.0. The web integration keeps the engine version, package version and schema version distinct so a package release does not silently imply a new calculation behavior.

The engine calculates; GetBirthChart's interpretation layer reads the structured result and applies its own evidence and output contracts.