Natal Charts

Overview

Natal chart endpoints calculate astrological charts based on birth date, time, and location. These are the foundation of astrological analysis.

---

POST /ephemeris/natal-chart

Calculate a natal chart with planetary positions, houses, aspects, and optional extended outputs.

Output Modes

The endpoint uses an output contract split into compute vs projection:

• Compute via preset=full|simple
• Projection via format=json|llm_v2

Common combinations:

• preset=full&format=json (default) - Complete enhanced natal chart with all calculated data
• preset=simple&format=json - Lightweight response with a lean dataset
• preset=full&format=llm_v2 - Deterministic row-based projection for LLM consumption

Aliases:

• format=llm is accepted as an alias for format=llm_v2

POST /ephemeris/natal-chart?preset=full&format=json  // Default
POST /ephemeris/natal-chart?preset=simple&format=json
POST /ephemeris/natal-chart?preset=full&format=llm_v2

Request Body

{
  subject: {
    name: string;
    birth_datetime: { iso: string };  // ISO 8601 format
    birth_location: {
      latitude: { decimal: number };
      longitude: { decimal: number };
      timezone: { iana_name: string };  // e.g., "America/New_York"
    };
  };
  configuration?: {
    house_system?: "P" | "K" | "W" | "E" | "C" | "R";  // Default: "P"
    zodiac_type?: "tropical" | "sidereal";  // Default: "tropical"
    coordinate_system?: "geocentric" | "heliocentric" | "topocentric";
    object_set?: "traditional_7" | "modern_10" | "modern_plus_chiron" | "asteroids_major" | "full" | "custom";
  };
  options?: {
    include_aspects?: boolean;
    include_hermetic_lots?: boolean;
    verbosity?: "minimal" | "standard" | "detailed";
  };
}

Configuration Options

| Field | Options | Description | |-------|---------|-------------| | house_system | P, K, W, E, C, R | Placidus, Koch, Whole Sign, Equal, Campanus, Regiomontanus | | zodiac_type | tropical, sidereal | Zodiac calculation method | | coordinate_system | geocentric, heliocentric, topocentric | Perspective for calculations | | object_set | traditional_7, modern_10, modern_plus_chiron, asteroids_major, full, custom | Which celestial bodies to include |

Response

The response is a discriminated union based on output_mode:

Full Mode Response (default)

{
  success: true;
  output_mode: "full";
  schema_version: "full_v1";
  data: {
    subject: SubjectInfo;
    planets: {
      sun: PlanetPosition;
      moon: PlanetPosition;
      mercury: PlanetPosition;
      // ... other planets
    };
    houses: {
      first: HouseInfo;
      second: HouseInfo;
      // ... 12 houses
    };
    aspects: Aspect[];
    hermetic_lots?: HermeticLot[];
    metadata: {
      calculation_time: string;
      house_system: string;
      zodiac_type: string;
    };
  };
  metadata?: {
    processing_time_ms: number;
  };
}

Simple Mode Response

{
  success: true;
  output_mode: "simple";
  schema_version: "simple_v1";
  data: {
    subject: SubjectInfo;
    houses: HousesResponse;
    angles: AnglesResponse;
    planets: {  // Core planets only (Sun-Pluto)
      [planetName: string]: SimplePlanetResponse;
    };
    aspects: SimpleAspect[];  // Major aspects only
  };
  metadata?: {
    processing_time_ms: number;
  };
}

LLM Mode Response

{
  success: true;
  output_mode: "llm_v2";
  schema_version: "llm_v2";
  preset: "full" | "simple";
  format: "llm_v2";
  data: {
    schema_version: "llm_v2";
    points_schema: string[];
    points: unknown[][];
    aspects_schema: string[];
    aspects: unknown[][];
  };
  metadata?: {
    processing_time_ms: number;
  };
}

Note: format=llm_v2 responses are always JSON (not plaintext).

Note: ACG endpoints (/acg/*) do not support format=llm_v2 and will return HTTP 400 with error "LLMModeNotSupported".

Example Request

curl -X POST https://api.astromcp.io/ephemeris/natal-chart \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "name": "Example Person",
      "birth_datetime": { "iso": "1990-06-15T14:30:00" },
      "birth_location": {
        "latitude": { "decimal": 40.7128 },
        "longitude": { "decimal": -74.0060 },
        "timezone": { "iana_name": "America/New_York" }
      }
    },
    "configuration": {
      "house_system": "P",
      "include_aspects": true
    }
  }'

---

Related Endpoints

• Calculations - Fixed stars, midpoints, hermetic lots, lunar phase
• Relocation - Relocate natal charts
• Progressed Charts - Secondary progressions
• Transit Charts - Current planetary transits
• Returns - Solar and lunar returns