API Documentation

Authentication

Authenticate your requests by including your API key in the x-api-key header.

bash

curl -H "x-api-key: YOUR_API_KEY" https://api.freeastroapi.com/v1/natal

Endpoints

POSTCalculate Natal Chart

Generates a complete natal chart with planetary positions, house cusps, and aspects.

Request Body

{
  "name": "John Doe",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "New York",
  "lat": 40.7128,
  "lng": -74.0060
}

Query Parameters:

include_minor (boolean, default false) – Return all 10 aspect types when true. By default only major aspects (Conjunction, Opposition, Trine, Square, Sextile) are returned.

Response (JSON)

{
  "subject": {
    "name": "John Doe",
    "city": "New York",
    "tz_str": "America/New_York",
    "zodiac_type": "Tropic"
  },
  "planets": [
    {
      "name": "Sun",
      "sign": "Tau",
      "pos": 24.72,
      "abs_pos": 54.72,
      "house": 9,
      "retrograde": false
    },
    {
      "name": "Moon",
      "sign": "Aqu",
      "pos": 14.23,
      "abs_pos": 314.23,
      "house": 5,
      "retrograde": false
    }
    // ... other planets
  ],
  "houses": [
    { "house": 1, "sign": "Vir", "degree": 18.5 },
    { "house": 10, "sign": "Gem", "degree": 16.2 }
    // ... 12 houses
  ],
  "aspects": [
    {
      "p1": "Sun",
      "p2": "Moon",
      "type": "Square",
      "orb": 5.5,
      "deg": 90.0,
      "is_major": true
    },
    {
      "p1": "Mars",
      "p2": "Jupiter",
      "type": "Trine",
      "orb": 2.1,
      "deg": 120.0,
      "is_major": true
    }
    // ... other aspects
  ],
  "aspects_summary": {
    "total": 24,
    "major": 24,
    "minor": 0,
    "by_type": {
      "Trine": 6,
      "Square": 8,
      "Conjunction": 3,
      "Sextile": 5,
      "Opposition": 2
    }
  }
}

POSTCalculate Transits

Calculates planetary transits for a specific date and location relative to a natal chart.

Request Body

{
  "natal": { ... }, // Same structure as Natal request
  "transit_date": "2025-11-20T12:00",
  "current_lat": 48.8566,
  "current_lng": 2.3522,
  "current_city": "Paris"
}

Query Parameters:

include_minor (boolean, default false) – Return all aspect types when true. By default only major aspects are returned.

Response (JSON)

{
  "transit_date": "2025-11-20",
  "location": {"city":"Paris","lat":48.8566,"lng":2.3522},
  "transit_planets": [...],
  "aspects": [
    {"p1":"Sun","p2":"Moon","type":"Conjunction","orb":0.96,"deg":0,"is_major":true},
    ...
  ],
  "aspects_summary": {
    "total": 88,
    "major": 88,
    "minor": 0,
    "by_type": {"Conjunction":11,"Opposition":18,"Trine":12,"Square":9,"Sextile":18,"Quintile":3,"Semi-sextile":6,"Semi-square":5,"Sesquiquadrate":6},
    "exact": 15
  }
}