Chart Data Factory #

The ChartDataFactory extracts and structures all astronomical calculations into machine-readable Pydantic models. It separates the computational layer from the visualization layer (ChartDrawer).

Key Features #

• Structured Output: Returns Pydantic models (SingleChartDataModel or DualChartDataModel) perfect for APIs.
• Automatic Analysis: Calculates element/quality distributions and relationship scores automatically.
• Optimized: Only calculates what is necessary for the requested chart type.

Factory Methods #

1. create_natal_chart_data #

Calculates all standard chart data (planets, houses, aspects, elements) for a single subject.

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory

subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=-0.1276, lat=51.5074, tz_str="Europe/London",
    online=False
)
natal_data = ChartDataFactory.create_natal_chart_data(subject)

print(f"Elements: {natal_data.element_distribution.fire_percentage}% Fire")
print(f"Qualities: {natal_data.quality_distribution.cardinal_percentage}% Cardinal")

Parameters #

See Element & Quality Distribution for details on distribution methods and custom weights.

2. create_synastry_chart_data #

Used for comparing two subjects. Includes relationship scoring and house comparison.

subject_b = AstrologicalSubjectFactory.from_birth_data(
    "Bob", 1992, 8, 20, 14, 30,
    lng=-74.006, lat=40.7128, tz_str="America/New_York",
    online=False
)

synastry_data = ChartDataFactory.create_synastry_chart_data(
    subject,
    subject_b,
    include_relationship_score=True,
    include_house_comparison=True
)

if synastry_data.relationship_score:
    print(f"Compatibility Score: {synastry_data.relationship_score.score_value}")

Parameters #

3. create_transit_chart_data #

Compares a natal chart against a current/event time subject.

now = AstrologicalSubjectFactory.from_current_time("Now", "London", "GB")
transit_data = ChartDataFactory.create_transit_chart_data(subject, now)

Parameters #

4. create_composite_chart_data #

Creates data for a composite (midpoint) chart from a CompositeSubjectModel.

from kerykeion import CompositeSubjectFactory

composite_subject = CompositeSubjectFactory(subject_a, subject_b).get_midpoint_composite_subject_model()
composite_data = ChartDataFactory.create_composite_chart_data(composite_subject)

Parameters #

5. create_return_chart_data #

Creates a dual-wheel planetary return chart (natal + return overlay).

from kerykeion import PlanetaryReturnFactory

return_factory = PlanetaryReturnFactory(natal_subject, city="New York", nation="US")
solar_return = return_factory.next_return_from_date(2024, 1, 1, return_type="Solar")

return_data = ChartDataFactory.create_return_chart_data(natal_subject, solar_return)

Parameters #

6. create_single_wheel_return_chart_data #

Creates a single-wheel view of a planetary return (return only, no natal overlay).

single_return_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return)

Parameters #

7. create_chart_data (Generic) #

The underlying generic method that all convenience methods delegate to. Use this when you need full control over the chart type.

chart_data = ChartDataFactory.create_chart_data(
    chart_type="Natal",
    first_subject=subject,
    distribution_method="pure_count"
)

Data Models #

SingleChartDataModel #

Used for Natal, Composite, and Single Return charts.

• subject: The AstrologicalSubjectModel.
• aspects: List of internal aspects.
• element_distribution: Fire/Earth/Air/Water breakdown.
• quality_distribution: Cardinal/Fixed/Mutable breakdown.

DualChartDataModel #

Used for Synastry, Transit, and Dual Return charts.

• first_subject, second_subject: The two subjects.
• aspects: Inter-chart aspects.
• relationship_score: Compatibility score (if requested).
• house_comparison: Planet overlays in houses (if requested).

Analysis Example #

Get a full JSON dump of a chart’s data.

import json
natal_data = ChartDataFactory.create_natal_chart_data(subject)

# Dump to JSON
json_output = natal_data.model_dump_json(indent=2)
print(json_output)

---

Need this in production? Use the Astrologer API for hosted calculations, charts, and AI interpretations - no server setup required. Learn more →