LILIT's astrological API service

a python-based api service for performing advanced astrological calculations.

---

local development

install:

make install

run:

make dev

---

endpoints overview

endpoint	Method	Description
/api/v1/birth-chart	POST	generates a full birth chart as an SVG string, including planetary positions and aspects.
/api/v1/synastry-chart	POST	creates a synastry chart comparing two subjects, displaying their interactions and compatibility, along with an SVG representation.
/api/v1/transit-chart	POST	generates a transit chart for a subject, showing current planetary influences, with an SVG visual representation.
/api/v1/composite-chart	POST	computes a composite chart for two subjects using the midpoint method, including aspects and an SVG visual representation.
/api/v1/relationship-score	POST	calculates a compatibility score (0-44) using the ciro discepolo method to assess relationship potential.
/api/v1/natal-aspects-data	POST	provides detailed birth chart data and aspects without the visual chart.
/api/v1/synastry-aspects-data	POST	returns synastry-related data and aspects between two subjects, without an SVG chart.
/api/v1/transit-aspects-data	POST	offers transit chart data and aspects for a subject, without an SVG visual representation.
/api/v1/composite-aspects-data	POST	delivers composite chart data and aspects without generating an SVG chart.
/api/v1/birth-data	POST	returns essential birth chart data without aspects or visual representation.
/api/v1/now	GET	retrieves birth chart data for the current UTC time, excluding aspects and the visual chart.

example API request:

{
    "subject": {
        "year": 1980,
        "month": 12,
        "day": 12,
        "hour": 12,
        "minute": 12,
        "longitude": 0,
        "latitude": 51.4825766,
        "city": "London",
        "nation": "GB",
        "timezone": "Europe/London",
        "name": "John Doe",
        "zodiac_type": "Tropic"
    },
    "language": "RU"
}

---

theme

you can change the theme to dark or light:

{
    "subject": { /* ... */ },
    "theme": "dark"
}

---

house system

whole house systems are default, and can be specified with: W. example API request:

{
    "subject": {
        "year": 1980,
        "month": 12,
        "day": 12,
        "hour": 12,
        "minute": 12,
        "longitude": 0,
        "latitude": 51.4825766,
        "city": "London",
        "nation": "GB",
        "timezone": "Europe/London",
        "name": "John Doe",
        "zodiac_type": "Tropic",
        "house_system": "W"
    }
}

---

perspective types

defines the viewpoint from which the positions of celestial bodies are calculated. here are the available options:

• "apparent geocentric": earth-centered and shows the apparent positions of celestial bodies as seen from earth. this is the most commonly used and the default perspective.
• "heliocentric": sun-centered.
• "topocentric": based on the observer's specific location on the Earth's surface.
• "true geocentric": earth-centered but shows the true positions of celestial bodies without the apparent shifts caused by earth's atmosphere.

example usage in an API request:

{
    "subject": {
        "year": 1980,
        "month": 12,
        "day": 12,
        "hour": 12,
        "minute": 12,
        "longitude": 0,
        "latitude": 51.4825766,
        "city": "London",
        "nation": "GB",
        "timezone": "Europe/London",
        "name": "John Doe",
        "zodiac_type": "Tropic",
        "perspective": "Heliocentric"
    }
}

---

timezones

accurate astrological calculations require the correct timezone (list of TZ database time zones).

---

active points and aspects

example API request:

{
    "subject": {
        "year": 1980,
        "month": 12,
        "day": 12,
        "hour": 12,
        "minute": 12,
        "longitude": 0,
        "latitude": 51.4825766,
        "city": "London",
        "nation": "GB",
        "timezone": "Europe/London",
        "name": "John Doe",
        "zodiac_type": "Tropic"
    },
    "active_points": [
        "Sun",
        "Moon",
        "Mercury",
        "Venus",
        "Mars",
        "Jupiter",
        "Saturn",
        "Uranus",
        "Neptune",
        "Pluto",
        "Mean_Node",
        "Chiron",
        "Ascendant",
        "Medium_Coeli",
        "Mean_Lilith",
        "Mean_South_Node"
    ],
    "active_aspects": [
        {
            "name": "conjunction",
            "orb": 10
        },
        {
            "name": "opposition",
            "orb": 10
        },
        {
            "name": "trine",
            "orb": 8
        },
        {
            "name": "sextile",
            "orb": 6
        },
        {
            "name": "square",
            "orb": 5
        },
        {
            "name": "quintile",
            "orb": 1
        }
    ]
}

geonames username

to calculate coordinates automatically, you need to obtain a username for the Geonames Timezone service. the service is free for up to 10,000 requests per day (Geonames). example of API:

{
    "subject": {
        "year": 1980,
        "month": 12,
        "day": 12,
        "hour": 12,
        "minute": 12,
        "city": "Jamaica, New York",
        "nation": "US",
        "name": "John Doe",
        "zodiac_type": "Tropic",
        "geonames_username": "YOUR_GEONAMES_USERNAME"
    }
}