FreeAstroAPI

https://www.freeastroapi.com/docs/
Admin
FreeAstroAPI offers a comprehensive astrology API with support for Western, Vedic, and Chinese...
Tokens:379,469
Snippets:1,892
Trust Score:3.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Electional Starting Journey API Response Example

Source: https://www.freeastroapi.com/docs/western/electional/starting-journey

This is a sample JSON response from the Starting Journey API. It includes metadata about the search and a ranked list of potential starting points with their scores, confidence levels, and supporting/cautionary factors.

```json
{
  "meta": {
    "endpoint": "/api/v2/western/electional/starting-journey/search",
    "scoring_version": "clean_room_starting_journey_v1",
    "calibration_version": "internal_calibration_v1",
    "search_mode": "direct",
    "window_strategy": "direct",
    "ranking_basis": "Comparative ranking is relative to the scanned search window after year-mode refinement when used.",
    "resolved_timezone": "Europe/Paris",
    "scanned_candidates": 10,
    "coarse_candidates_scanned": 10,
    "refined_candidates_scanned": 0,
    "returned_candidates": 1,
    "advisories": [],
    "search_start_local": "2026-06-01T09:00:00+02:00",
    "search_end_local": "2026-06-01T18:00:00+02:00",
    "step_minutes": 60
  },
  "results": [
    {
      "rank": 1,
      "event_time_local": "2026-06-01T18:00:00+02:00",
      "event_time_utc": "2026-06-01T16:00:00Z",
      "score_total": 21,
      "confidence_level": "low",
      "quality_band": "poor",
      "status": "reject",
      "strict_traditional_verdict": "blemished",
      "strict_traditional_severity": "major",
      "comparative_window_rank": 1,
      "comparative_window_percentile": 100,
      "best_available_in_window": true,
      "review_flags": [
        "moon_void_of_course_stop"
      ],
      "hard_stops": [
        {
          "code": "moon_void_of_course_stop",
          "title": "Moon void of course",
          "score": 0,
          "detail": "Moon void of course",
          "severity": "major"
        }
      ],
      "supporting_factors": [
        {
          "code": "mercury_direct",
          "title": "Mercury direct",
          "score": 6,
          "detail": "Mercury direct"
        },
        {
          "code": "mercury_unafflicted",
          "title": "Mercury free from hard malefic pressure",
          "score": 6,
          "detail": "Mercury free from hard malefic pressure"
        },
        {
          "code": "moon_supportive_house",
          "title": "Moon in a mobility-supportive house",
          "score": 5,
          "detail": "Moon in a mobility-supportive house"
        },
        {
          "code": "mercury_supportive_house",
          "title": "Mercury in a mobility-supportive house",
          "score": 5,
          "detail": "Mercury in a mobility-supportive house"
        }
      ],
      "caution_factors": [
        {
          "code": "moon_waning",
          "title": "Waning Moon",
          "score": -3,
          "detail": "Waning Moon"
        }
      ],
      "natal_resonance": null
    }
  ]
}
```

--------------------------------

### Vedic Gochar Timeline Request Example

Source: https://www.freeastroapi.com/docs/vedic/gochar-timeline

A real-world request example for the Vedic Gochar Timeline API, demonstrating the required parameters for generating a transit timeline.

```APIDOC
## Real Request Example

```json
{
  "year": 1997,
  "month": 9,
  "day": 22,
  "hour": 23,
  "minute": 25,
  "city": "Mumbai",
  "lat": 19.391928,
  "lng": 72.839732,
  "tz_str": "Asia/Kolkata",
  "ayanamsha": "lahiri",
  "house_system": "whole_sign",
  "node_type": "mean",
  "range_start": "2026-04-01",
  "range_end": "2026-04-03",
  "transit_hour": 12,
  "transit_minute": 0,
  "transit_tz_str": "Asia/Kolkata",
  "transit_planets": [
    "saturn",
    "jupiter",
    "rahu",
    "ketu"
  ],
  "include_dasha_overlay": false
}
```
```

--------------------------------

### Real Monthly Example

Source: https://www.freeastroapi.com/docs/western/transits/timeline

This example demonstrates how to fetch a monthly transit timeline for a specific natal chart, filtered by 'medium' and 'slow' transit categories.

```APIDOC
## POST /api/v1/western/transits/timeline

### Description
Retrieves a timeline of astrological transits for a given month or year based on a natal chart.

### Method
POST

### Endpoint
/api/v1/western/transits/timeline

### Parameters
#### Request Body
- **mode** (string) - Required - Specifies the time frame for the transits ('month' or 'year').
- **natal** (object) - Required - Contains the details of the natal chart.
  - **name** (string) - Required - The name of the individual.
  - **year** (integer) - Required - The birth year.
  - **month** (integer) - Required - The birth month (1-12).
  - **day** (integer) - Required - The birth day (1-31).
  - **hour** (integer) - Required - The birth hour (0-23).
  - **minute** (integer) - Required - The birth minute (0-59).
  - **time_known** (boolean) - Required - Indicates if the birth time is known.
  - **city** (string) - Required - The birth city.
  - **lat** (float) - Required - The birth latitude.
  - **lng** (float) - Required - The birth longitude.
  - **tz_str** (string) - Required - The time zone string (e.g., 'Europe/Paris').
  - **zodiac_type** (string) - Optional - The zodiac type ('sidereal' or 'tropical'). Defaults to 'tropical'.
  - **sidereal_ayanamsa** (string) - Optional - The ayanamsa to use if `zodiac_type` is 'sidereal' (e.g., 'lahiri').
- **range_start** (string) - Required - The start date for the transit range (YYYY-MM-DD).
- **range_end** (string) - Required - The end date for the transit range (YYYY-MM-DD).
- **include_houses** (boolean) - Optional - Whether to include house information in the response. Defaults to false.
- **transit_categories** (array of strings) - Optional - Filters transits by category (e.g., 'fast', 'medium', 'slow').

### Request Example
```json
{
    "mode": "month",
    "natal": {
        "name": "Gabriel",
        "year": 1995,
        "month": 9,
        "day": 5,
        "hour": 20,
        "minute": 0,
        "time_known": true,
        "city": "Paris",
        "lat": 48.8566,
        "lng": 2.3522,
        "tz_str": "Europe/Paris",
        "zodiac_type": "sidereal",
        "sidereal_ayanamsa": "lahiri"
    },
    "range_start": "2026-03-01",
    "range_end": "2026-03-31",
    "include_houses": true,
    "transit_categories": ["medium", "slow"]
}
```

### Response
#### Success Response (200)
- **meta** (object) - Metadata about the request and response.
  - **endpoint** (string) - The API endpoint used.
  - **version** (string) - The API version.
  - **range_start** (string) - The start of the requested range.
  - **range_end** (string) - The end of the requested range.
  - **generated_at** (string) - Timestamp when the response was generated.
- **input** (object) - The input parameters used for the request.
- **transits** (array of objects) - A list of astrological transits within the specified range.
  - **id** (string) - Unique identifier for the transit.
  - **series_key** (string) - Key representing the transit aspect and planets.
  - **category** (string) - Category of the transit ('fast', 'medium', 'slow').
  - **transit_planet** (string) - The transiting planet.
  - **natal_point** (string) - The natal point being aspected.
  - **aspect_type** (string) - The type of aspect (e.g., 'conjunction', 'opposition').
  - **label** (string) - A human-readable label for the transit.
  - **short_symbol_label** (string) - Short symbolic representation of the transit.
  - **start_datetime** (string) - The start date and time of the transit influence.
  - **exact_datetimes** (array of strings) - Exact dates and times when the aspect is exact.
  - **end_datetime** (string) - The end date and time of the transit influence.
  - **duration_days** (float) - The duration of the transit in days.
  - **pass_type** (string) - The type of transit pass ('direct', 'retrograde').
  - **visible_start_day** (integer) - The day within the range the transit becomes visible.
  - **visible_end_day** (integer) - The day within the range the transit ends.
  - **continues_from_previous_month** (boolean) - Indicates if the transit started before the current range.
  - **continues_to_next_month** (boolean) - Indicates if the transit continues after the current range.
  - **exact_hits_in_month** (array of strings) - Dates within the month when the aspect is exact.
  - **row_key** (string) - Internal key for grouping transits.
  - **pair_key** (string) - Internal key for the planet pair.
  - **houses** (object) - House information if `include_houses` is true.
    - **natal_point_house** (integer) - The natal house of the natal point.
    - **transit_house_at_exact** (integer) - The house the transiting planet is in at the exact aspect.
    - **transit_house_in_month** (integer) - The house the transiting planet is in during the month.

#### Response Example
```json
{
  "meta": {
    "endpoint": "western_transits_timeline",
    "version": "v1",
    "range_start": "2026-03-01T00:00:00Z",
    "range_end": "2026-03-31T23:59:59Z",
    "generated_at": "2026-04-06T12:59:02Z"
  },
  "input": {
    "mode": "month",
    "include_houses": true,
    "transit_categories": ["medium", "slow"],
    "transit_planets": ["jupiter", "saturn", "uranus", "neptune", "pluto", "north_node", "chiron"],
    "natal_points": ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "north_node", "ascendant", "midheaven", "descendant", "ic"],
    "aspect_types": ["conjunction", "square", "opposition", "trine", "sextile"]
  },
  "transits": [
    {
      "id": "transit.opposition.uranus.pluto@2026-02-04T02:22:01Z",
      "series_key": "transit.opposition.uranus.pluto",
      "category": "slow",
      "transit_planet": "uranus",
      "natal_point": "pluto",
      "aspect_type": "opposition",
      "label": "Uranus Opposition Natal Pluto",
      "short_symbol_label": "♅ ☍ ♇",
      "start_datetime": "2026-02-04T02:22:01Z",
      "exact_datetimes": ["2026-03-12T15:56:15Z"],
      "end_datetime": "2026-09-10T17:22:01Z",
      "duration_days": 218.625,
      "pass_type": "direct",
      "visible_start_day": 1,
      "visible_end_day": 31,
      "continues_from_previous_month": true,
      "continues_to_next_month": true,
      "exact_hits_in_month": ["2026-03-12T15:56:15Z"],
      "row_key": "uranus__opposition__pluto",
      "pair_key": "uranus__pluto",
      "houses": {
        "natal_point_house": 4,
        "transit_house_at_exact": 11,
        "transit_house_in_month": 11
      }
    },
    {
      "id": "transit.opposition.north_node.sun@2025-07-23T19:52:30Z",
      "series_key": "transit.opposition.north_node.sun",
      "category": "slow",
      "transit_planet": "north_node",
      "natal_point": "sun",
      "aspect_type": "opposition",
      "label": "North Node Opposition Natal Sun",
      "short_symbol_label": "☊ ☍ ☉",
      "start_datetime": "2025-07-23T19:52:30Z",
      "exact_datetimes": ["2025-12-21T21:49:13Z"],
      "end_datetime": "2026-05-21T23:45:56Z",
      "duration_days": 302.162109,
      "pass_type": "retrograde",
      "visible_start_day": 1,
      "visible_end_day": 31,
      "continues_from_previous_month": true,
      "continues_to_next_month": true,
      "exact_hits_in_month": [],
      "row_key": "north_node__opposition__sun",
      "pair_key": "north_node__sun"
    }
  ]
}
```
```

--------------------------------

### Primary Direction Example

Source: https://www.freeastroapi.com/docs/western/symbolic-directions

Example of a primary direction calculation response, showing aspects between planets and their timing.

```json
{
      "promissor_natal_longitude_deg": 333.267655,
      "directed_longitude_deg": 10.814261,
      "significator_longitude_deg": 280.814261,
      "measurement": "zodiacal",
      "orb_years": 1,
      "active_window": {
        "from": "2026-07-19",
        "exact": "2027-07-20",
        "to": "2028-07-19",
        "from_datetime_utc": "2026-07-19T20:41:56.653878Z",
        "exact_datetime_utc": "2027-07-20T02:30:41.783478Z",
        "to_datetime_utc": "2028-07-19T08:19:26.913078Z",
        "from_datetime_local": "2026-07-19T21:41:56.653878+01:00",
        "exact_datetime_local": "2027-07-20T03:30:41.783478+01:00",
        "to_datetime_local": "2028-07-19T09:19:26.913078+01:00"
      },
      "interpretation_key": "primary_direction.direct.square.moon.sun"
    }
```

--------------------------------

### Real Response Example: Pressure Window for Moon

Source: https://www.freeastroapi.com/docs/western/transit-insights

This JSON object shows a 'pressure_window' insight from the Transit Insights API, focusing on the Moon. It includes details on the detector, subjects, strength, priority, evidence, and associated flags, tags, and entities, similar to other pressure window responses.

```json
{
      "id": "transit_insight.pressure_window.moon.2026-09-23T11:05:09Z",
      "category": "emotions",
      "detector": "activation_clusters.pressure_windows.v1",
      "kind": "pressure_window",
      "subjects": [
        "neptune",
        "sun",
        "moon"
      ],
      "strength": 0.62,
      "priority": 85,
      "evidence": {
        "window_type": "pressure",
        "focus_point": "moon",
        "start_datetime": "2026-07-07T12:00:00Z",
        "end_datetime": "2026-12-13T00:00:00Z",
        "peak_datetime": "2026-09-23T11:05:09Z",
        "source_pass_ids": [
          "transit.conjunction.neptune.moon@2026-07-07T12:00:00Z",
          "transit.opposition.sun.moon@2026-09-15T06:26:43Z"
        ],
        "source_series_keys": [
          "transit.conjunction.neptune.moon",
          "transit.opposition.sun.moon"
        ],
        "transit_planets": [
          "neptune",
          "sun"
        ],
        "natal_points": [
          "moon"
        ],
        "houses": [
          10
        ],
        "pass_count": 2,
        "aspect_types": [
          "conjunction",
          "opposition"
        ],
        "unique_transit_planet_count": 2
      },
      "flags": {
        "derived": true,
        "time_dependent": true,
        "house_based": true
      },
      "tags": [
        "aspect_type:conjunction",
        "aspect_type:opposition",
        "category:emotions",
        "detector:activation_clusters.pressure_windows.v1",
        "house:10",
        "house_based:true",
        "kind:pressure_window",
        "planet:moon",
        "planet:neptune",
        "planet:sun",
        "relation:pressure_window__moon",
        "score_bucket:medium"
      ]
```

--------------------------------

### Real Transit Insights Response Example

Source: https://www.freeastroapi.com/docs/western/transit-insights

This JSON object shows a real response from the Transit Insights API, detailing metadata, summary statistics by category, kind, priority, and detector, as well as a list of important transit events.

```json
{
  "meta": {
    "endpoint": "western_transit_insights",
    "detector_version": "transit_insights_v2",
    "mode": "month",
    "range_start": "2026-10-01T00:00:00Z",
    "range_end": "2026-10-31T23:59:59Z",
    "generated_at": "2026-04-16T16:12:00Z",
    "time_known": true,
    "include_houses": true,
    "timeline_pass_count": 76,
    "generated_fact_count": 61
  },
  "summary": {
    "by_category": {
      "chart_pattern": 10,
      "drive": 2,
      "emotions": 5,
      "growth": 1,
      "identity": 7,
      "life_path": 6,
      "mind": 6,
      "relationships": 8,
      "structure": 2,
      "transformation": 14
    },
    "by_kind": {
      "activation_cluster": 14,
      "angular_activation": 1,
      "configuration": 8,
      "ingress": 12,
      "pressure_window": 8,
      "station": 3,
      "stellium": 3,
      "support_window": 12
    },
    "by_priority": {
      "72": 12,
      "78": 3,
      "82": 14,
      "84": 1,
      "85": 20,
      "86": 3,
      "90": 8
    },
    "by_detector": {
      "activation_clusters.angular_points.v1": 1,
      "activation_clusters.pressure_windows.v1": 8,
      "activation_clusters.repeated_point.v1": 13,
      "activation_clusters.retrograde_cycle.v1": 1,
      "activation_clusters.support_windows.v1": 12,
      "configurations.transit_patterns.v1": 8,
      "station_ingress_events.house_ingresses.v1": 10,
      "station_ingress_events.sign_ingresses.v1": 2,
      "station_ingress_events.stations.v1": 3,
      "stelliums.house.v1": 1,
      "stelliums.sign.v1": 2
    }
  },
  "importance": [
    {
      "id": "importance.identity:activation_cluster",
      "title": "Activation Cluster  Sun",
      "category": "identity",
      "score": 1,
      "rank": 1,
      "source_fact_ids": [
        "transit_insight.activation_cluster.sun.2026-10-09T09:08:26Z"
      ],
      "driver_tags": [
        "category:identity",
        "detector:activation_clusters.repeated_point.v1",
        "kind:activation_cluster",
        "relation:activation_cluster__sun"
      ]
    },
    {
      "id": "importance.life_path:activation_cluster",
      "title": "Activation Cluster  Mean Node",
      "category": "life_path",
      "score": 1,
      "rank": 2,
      "source_fact_ids": [
        "transit_insight.activation_cluster.mean_node.2026-09-27T05:03:45Z",
        "transit_insight.activation_cluster.true_node.2026-09-27T22:17:20Z"
      ],
      "driver_tags": [
        "category:life_path",
        "detector:activation_clusters.repeated_point.v1",
        "kind:activation_cluster",
        "relation:activation_cluster__mean_node",
        "relation:activation_cluster__true_node"
      ]
    },
    {
      "id": "importance.mind:activation_cluster",
      "title": "Activation Cluster  Mercury",
      "category": "mind",
      "score": 1,
      "rank": 3,
      "source_fact_ids": [
        "transit_insight.activation_cluster.mercury.2026-09-04T03:14:03Z"
      ],
      "driver_tags": [
        "category:mind",
        "detector:activation_clusters.repeated_point.v1",
        "kind:activation_cluster",
        "relation:activation_cluster__mercury"
      ]
    },
    {
      "id": "importance.transformation:activation_cluster",
      "title": "Activation Cluster  Uranus",
      "category": "transformation",
      "score": 0.989,
      "rank": 4,
      "source_fact_ids": [
        "transit_insight.activation_cluster.uranus.2026-09-22T20:00:56Z"
      ],
      "driver_tags": [
        "category:transformation",
        "detector:activation_clusters.repeated_point.v1",
        "kind:activation_cluster",
        "relation:activation_cluster__uranus"
      ]
    },
    {
      "id": "importance.relationships:activation_cluster",
      "title": "Activation Cluster  Venus",
      "category": "relationships",
      "score": 0.974,
      "rank": 5,
      "source_fact_ids": [
        "transit_insight.activation_cluster.venus.2026-08-09T05:01:38Z"
      ],
      "driver_tags": [
        "category:relationships",
        "detector:activation_clusters.repeated_point.v1",
        "kind:activation_cluster",
        "relation:activation_cluster__venus"
      ]
    },
    {
      "id": "importance.chart_pattern:configuration",
      "title": "Transit Kite",
      "category": "chart_pattern",
      "score": 0.97,
      "rank": 6,
      "source_fact_ids": [
        "transit_insight.configuration.grand_trine:pluto.sun.uranus.2026-10-02T12:00:00Z"
      ],
      "driver_tags": [
        "category:chart_pattern",
        "detector:configurations.transit_patterns.v1",
        "kind:configuration",
        "relation:configuration__grand_trine"
      ]
    }
  ]
}
```

--------------------------------

### Real Response Example: Pressure Window for Chiron

Source: https://www.freeastroapi.com/docs/western/transit-insights

This JSON object represents a real response from the Transit Insights API, detailing a 'pressure_window' insight related to Chiron. It includes information about the detector, subjects, strength, priority, evidence of the transit, and associated flags, tags, entities, and search text.

```json
{
      "detector": "activation_clusters.pressure_windows.v1",
      "kind": "pressure_window",
      "subjects": [
        "neptune",
        "saturn",
        "chiron"
      ],
      "strength": 0.62,
      "priority": 85,
      "evidence": {
        "window_type": "pressure",
        "focus_point": "chiron",
        "start_datetime": "2026-07-07T09:05:37Z",
        "end_datetime": "2026-12-12T21:05:37Z",
        "peak_datetime": "2026-09-24T15:05:37Z",
        "source_pass_ids": [
          "transit.opposition.neptune.chiron@2026-07-07T09:05:37Z",
          "transit.opposition.saturn.chiron@2026-07-26T20:17:48Z"
        ],
        "source_series_keys": [
          "transit.opposition.neptune.chiron",
          "transit.opposition.saturn.chiron"
        ],
        "transit_planets": [
          "neptune",
          "saturn"
        ],
        "natal_points": [
          "chiron"
        ],
        "houses": [
          4
        ],
        "pass_count": 2,
        "aspect_types": [
          "opposition"
        ],
        "unique_transit_planet_count": 2
      },
      "flags": {
        "derived": true,
        "time_dependent": true,
        "house_based": true
      },
      "tags": [
        "aspect_type:opposition",
        "category:transformation",
        "detector:activation_clusters.pressure_windows.v1",
        "house:4",
        "house_based:true",
        "kind:pressure_window",
        "planet:chiron",
        "planet:neptune",
        "planet:saturn",
        "relation:pressure_window__chiron",
        "score_bucket:medium",
        "time_dependent:true"
      ],
      "entities": {
        "planets": [
          "chiron",
          "neptune",
          "saturn"
        ],
        "signs": [],
        "houses": [
          4
        ],
        "aspect_types": [
          "opposition"
        ],
        "configuration_types": [],
        "categories": [
          "transformation"
        ]
      },
      "search_text": "transit_insight.pressure_window.chiron.2026-09-24T15:05:37Z transformation activation_clusters.pressure_windows.v1 pressure_window pressure_window__chiron neptune saturn chiron 2026-09-24T15:05:37Z 2026-07-07T09:05:37Z 2026-12-12T21:05:37Z neptune saturn chiron aspect_type:opposition category:transformation detector:activation_clusters.pressure_windows.v1 house:4 house_based:true kind:pressure_window planet:chiron planet:neptune planet:saturn relation:pressure_window__chiron score_bucket:medium time_dependent:true aspect_type_id:opposition detector:activation_clusters.pressure_windows.v1 house_id:4 id:transit_insight.pressure_window.chiron.2026-09-24T15:05:37Z kind:pressure_window planet_id:chiron planet_id:neptune planet_id:saturn priority:85 relation:pressure_window__chiron score_bucket:medium",
      "relation_key": "pressure_window__chiron",
      "index_keys": [
        "aspect_type_id:opposition",
        "detector:activation_clusters.pressure_windows.v1",
        "house_id:4",
        "id:transit_insight.pressure_window.chiron.2026-09-24T15:05:37Z",
        "kind:pressure_window",
        "planet_id:chiron",
        "planet_id:neptune",
        "planet_id:saturn",
        "priority:85",
        "relation:pressure_window__chiron",
        "score_bucket:medium"
      ]
    }
```

--------------------------------

### Get Today's Chinese Pillars (Node.js)

Source: https://www.freeastroapi.com/docs/chinese/today

This Node.js example uses the 'axios' library to fetch today's Chinese astrological pillars. Make sure to install axios and replace 'YOUR_API_KEY' with your actual key.

```javascript
const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const url = 'https://api.freeastroapi.com/api/v1/chinese/today';

axios.get(url, {
  headers: {
    'x-api-key': apiKey
  }
})
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error.response.status);
  });

```

--------------------------------

### Quaternary Progression (Default Mode)

Source: https://www.freeastroapi.com/docs/western/progressions/quaternary

This example demonstrates the minimal request for the Quaternary progression system, returning results in the default JSON format.

```APIDOC
## POST /api/v1/western/progressions/quaternary

### Description
Calculates symbolic progressions using the Quaternary system, which is a faster method based on a lunar-month-for-year mapping, suitable for compressed timing experiments.

### Method
POST

### Endpoint
/api/v1/western/progressions/quaternary

### Parameters
#### Request Body
- **natal** (object) - Required - Natal chart details including name, datetime, time_known, and location.
  - **name** (string) - Required - Name of the individual.
  - **datetime** (string) - Required - Date and time of birth (YYYY-MM-DD HH:MM).
  - **time_known** (boolean) - Required - Indicates if the birth time is known.
  - **location** (object) - Required - Geographical location of birth.
    - **city** (string) - Required - City of birth.
    - **lat** (number) - Required - Latitude of the birth location.
    - **lng** (number) - Required - Longitude of the birth location.
    - **tz_str** (string) - Required - Timezone string (e.g., "AUTO").
- **quaternary_progression** (object) - Required - Parameters for the Quaternary progression.
  - **target_date** (string) - Required - The target date for the progression calculation (YYYY-MM-DD).

### Request Example
```json
{
  "natal": {
    "name": "User",
    "datetime": "1990-01-01 12:00",
    "time_known": true,
    "location": {
      "city": "London",
      "lat": 51.5074,
      "lng": -0.1278,
      "tz_str": "AUTO"
    }
  },
  "quaternary_progression": {
    "target_date": "2026-03-30"
  }
}
```

### Response
#### Success Response (200)
- **progressions** (object) - Contains the calculated quaternary progressions.
  - **quaternary** (array) - Array of quaternary progression details.
    - **date** (string) - The date of the progression event.
    - **event** (string) - Description of the progression event.
    - **symbol** (string) - The astrological symbol associated with the event.
    - **degree** (number) - The degree of the symbol.
    - **house** (number) - The house in which the event occurs.
    - **planet** (string) - The planet involved in the progression.
    - **sign** (string) - The sign in which the planet is located.
    - **aspects** (array) - Array of aspects made by the progressed planet.
      - **planet** (string) - The planet making the aspect.
      - **symbol** (string) - The astrological symbol of the aspect.
      - **degree** (number) - The degree of the aspect.
      - **house** (number) - The house in which the aspect occurs.
      - **sign** (string) - The sign in which the aspect occurs.

#### Response Example
```json
{
  "progressions": {
    "quaternary": [
      {
        "date": "2026-03-30",
        "event": "Sun conjunct Moon",
        "symbol": "☉",
        "degree": 15.5,
        "house": 7,
        "planet": "Sun",
        "sign": "Aries",
        "aspects": [
          {
            "planet": "Mars",
            "symbol": "☍",
            "degree": 16.0,
            "house": 7,
            "sign": "Aries"
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Get Ephemeris Table (GET)

Source: https://www.freeastroapi.com/docs/western/ephemeris

Retrieve a range of ephemeris data formatted as a grid, suitable for month-style calendar views. This example requests data for multiple celestial bodies.

```bash
curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
 -H "x-api-key: YOUR_API_KEY" \
 --data-urlencode "start=2026-03-01T00:00:00Z" \
 --data-urlencode "end=2026-03-31T00:00:00Z" \
 --data-urlencode "step=1d" \
 --data-urlencode "response_mode=table" \
 --data-urlencode "table_style=grid" \
 --data-urlencode "bodies=Sun,Moon,Mercury,Venus,Mars,Jupiter,Saturn,Uranus,Neptune,Pluto,Chiron,True_Lilith"
```

--------------------------------

### Sample Response from Parans API

Source: https://www.freeastroapi.com/docs/western/astrocartography/parans

This is a trimmed example of a successful response from the Parans API. It includes metadata, warnings, and a list of calculated parans with detailed information.

```json
{
  "meta": {
    "mode": "in_mundo",
    "bodies": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn",
      "uranus",
      "neptune",
      "pluto",
      "true_node"
    ],
    "events": ["asc", "dsc", "mc", "ic"],
    "timezone": "Europe/Paris",
    "paran_orb_deg": 1.0,
    "paran_tail_deg": 2.0,
    "geometry_format": "geojson",
    "coordinate_reference_system": "WGS84",
    "coordinate_order": "longitude_latitude",
    "count": 20
  },
  "warnings": [
    "Astrocartography results are exploratory and should be treated as directional rather than deterministic."
  ],
  "parans": [
    {
      "id": "sun:ic:jupiter:dsc:-21.105",
      "body_a": "sun",
      "event_a": "ic",
      "body_b": "jupiter",
      "event_b": "dsc",
      "latitude": -21.105,
      "orb_deg": 0.001,
      "geometry": {
        "type": "Polygon",
        "coordinates": [[ 
          [-180.0, -22.105],
          [180.0, -22.105],
          [180.0, -20.105],
          [-180.0, -20.105],
          [-180.0, -22.105]
        ]]
      },
      "nearest_cities": [
        {
          "name": "Ribeirão Preto",
          "country": "BR",
          "state": "Sao Paulo",
          "lat": -21.1775,
          "lng": -47.81028,
          "timezone": "America/Sao_Paulo",
          "population": 711825,
          "distance_km": 8.1
        },
        {
          "name": "Juiz de Fora",
          "country": "BR",
          "state": "Minas Gerais",
          "lat": -21.76417,
          "lng": -43.35028,
          "timezone": "America/Sao_Paulo",
          "population": 573285,
          "distance_km": 73.4
        }
      ],
      "strength": 1.0,
      "strongest_focus": "home",
      "secondary_focus": "health",
      "polarity": "supportive",
      "interpretation_short": "Sun IC with Jupiter DSC creates an expansion hotspot around 21.1° latitude. Best for home. Secondary pull: health.",
      "interpretation_caution": "Best use: expansion, confidence and recognition, while managing confidence can outrun realism, ego strain or burnout, excess or overreach.",
      "benefit_keywords": [
        "expansion",
        "confidence and recognition",
        "expansion and opportunity",
        "home and roots",
        "partnership and social mirroring",
        "home",
        "health"
      ],
      "risk_keywords": [
        "confidence can outrun realism",
        "ego strain or burnout",
        "excess or overreach",
        "mixed priorities"
      ]
    },
    {
      "id": "sun:mc:jupiter:asc:21.105",
      "body_a": "sun",
      "event_a": "mc",
      "body_b": "jupiter",
      "event_b": "asc",
      "latitude": 21.105,
      "orb_deg": 0.001,
      "...": "real response continues"
    },
    {
      "id": "sun:asc:jupiter:ic:51.254",
      "body_a": "sun",
      "event_a": "asc",
      "body_b": "jupiter",
      "event_b": "ic",
      "latitude": 51.254,
      "orb_deg": 0.0,
      "...": "real response continues"
    }
  ]
}
```

--------------------------------

### Get Today's Chinese Pillars (Python)

Source: https://www.freeastroapi.com/docs/chinese/today

This Python script demonstrates how to call the API to get today's Chinese astrological pillars. Ensure you have the 'requests' library installed.

```python
import requests

api_key = "YOUR_API_KEY"
url = "https://api.freeastroapi.com/api/v1/chinese/today"

headers = {
    "x-api-key": api_key
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### Sample API Response for Move-In Search

Source: https://www.freeastroapi.com/docs/western/electional/move-into-new-home

This is a trimmed example of a production API response for the move-into-new-home search. It includes metadata about the search and a list of potential event times with associated scores and advisories.

```json
{
  "meta": {
    "endpoint": "/api/v2/western/electional/move-into-new-home/search",
    "scoring_version": "clean_room_move_into_new_home_v1",
    "calibration_version": "internal_calibration_v1",
    "search_mode": "direct",
    "window_strategy": "direct",
    "ranking_basis": "Comparative ranking is relative to the scanned search window after year-mode refinement when used.",
    "resolved_timezone": "Europe/Paris",
    "scanned_candidates": 10,
    "coarse_candidates_scanned": 10,
    "refined_candidates_scanned": 0,
    "returned_candidates": 1,
    "advisories": [],
    "search_start_local": "2026-06-01T09:00:00+02:00",
    "search_end_local": "2026-06-01T18:00:00+02:00",
    "step_minutes": 60
  },
  "results": [
    {
      "rank": 1,
      "event_time_local": "2026-06-01T14:00:00+02:00",
      "event_time_utc": "2026-06-01T12:00:00Z",
      "score_total": 19,
      "confidence_level": "low",
      "quality_band": "poor",
      "status": "reject",
      "strict_traditional_verdict": "blemished",
      "strict_traditional_severity": "major",
      "comparative_window_rank": 1,
      "comparative_window_percentile": 100,
      "best_available_in_window": true,
      "review_flags": [
        "moon_void_of_course_stop"
      ],
      "hard_stops": [
        {
          "code": "moon_void_of_course_stop",
          "title": "Moon void of course",
          "score": 0,
          "detail": "Moon void of course",
          "severity": "major"
        }
      ],
      "supporting_factors": [
        {
          "code": "h4_ruler_dignified",
          "title": "4th ruler dignified",
          "score": 6,
          "detail": "4th ruler dignified"
        },
        {
          "code": "moon_supportive_house",
          "title": "Moon in a home-supportive house",
          "score": 5,
          "detail": "Moon in a home-supportive house"
        },
        {
          "code": "venus_supportive_house",
          "title": "Venus in a home-supportive house",
          "score": 5,
          "detail": "Venus in a home-supportive house"
        },
        {
          "code": "h4_ruler_supportive_house",
          "title": "Jupiter in a home-supportive house",
          "score": 5,
          "detail": "Jupiter in a home-supportive house"
        }
      ],
      "caution_factors": [
        {
          "code": "venus_malefic_pressure",
          "title": "Venus under hard malefic pressure",
          "score": -5,
          "detail": "Venus under hard malefic pressure"
        },
        {
          "code": "moon_waning",
          "title": "Waning Moon",
          "score": -3,
          "detail": "Waning Moon"
        }
      ],
      "natal_resonance": null
    }
  ]
}
```
Tokens:
Raw