AstroLib API

Professional REST API for natal chart calculations powered by Immanuel library

Quick Start • API Reference • Examples • License

🌟 Overview

AstroLib is a professional Flask REST API that exposes comprehensive natal chart calculations powered by the Immanuel library. The service serializes Immanuel data into a structured contract (default in Spanish, with multi-language support by Immanuel), including angles, houses, objects, aspects, dignities, sect, and chart metadata.

🚀 Quick Start

Prerequisites

Docker Desktop installed and running
Git for cloning the repository

Installation with Docker

Clone the repository
```
git clone <repository-url>
cd AstroLib
```

Build and run with Docker Compose

docker-compose up --build

Or using Docker directly:

docker build -t astrolib-api .
docker run -p 8080:8080 astrolib-api

Verify the service is running
```
curl http://localhost:8080/health
```

The API will be available at http://localhost:8080

📋 API Reference

Endpoint

Method: POST
Path: /api/v1/carta-natal
Content-Type: application/json

Request Schema

{
  "identidad": {
    "nombre": "string (optional)",
    "notas": "string (optional)"
  },
  "nacimiento": {
    "fecha": "YYYY-MM-DD",
    "hora": "HH:MM:SS",
    "lugar": {
      "ciudad": "string (optional)",
      "pais": "string (optional)",
      "coordenadas": {
        "latitud": "number (-90 to 90)",
        "longitud": "number (-180 to 180)"
      }
    },
    "zona_horaria": "string (optional)"
  },
  "referencias": {
    "zodiaco": "string (default: tropical)",
    "sistema_casas": "string (default: Plácidus)",
    "idioma": "string (es_ES or en_EN, default: es_ES)"
  }
}

📝 Examples

Sample Request

curl -X POST http://localhost:8080/api/v1/carta-natal \
  -H "Content-Type: application/json" \
  -d '{
    "identidad": {
      "nombre": "Example Person",
      "notas": "Optional biographical context"
    },
    "nacimiento": {
      "fecha": "1990-08-15",
      "hora": "14:35:00",
      "lugar": {
        "ciudad": "Madrid",
        "pais": "España",
        "coordenadas": {
          "latitud": 40.4168,
          "longitud": -3.7038
        }
      }
    },
    "referencias": {
      "zodiaco": "tropical",
      "sistema_casas": "Plácidus",
      "idioma": "es_ES"
    }
  }'

Sample Response

{
  "carta_natal": {
    "identidad": {
      "nombre": "Prueba",
      "notas": "Contexto biográfico opcional"
    },
    "nacimiento": {
      "fecha": "1990-08-15",
      "hora": "14:35:00",
      "lugar": {
        "ciudad": "Madrid",
        "pais": "España",
        "coordenadas": {
          "latitud": 40.4168,
          "longitud": -3.7038
        }
      }
    },
    "referencias": {
      "zodiaco": "tropical",
      "sistema_casas": "Plácidus",
      "idioma": "es_ES",
      "objetos_incluidos": [
        "Sol", "Luna", "Mercurio", "Venus", "Marte", "Júpiter", "Saturno",
        "Urano", "Neptuno", "Plutón", "Quirón", "Ceres", "Palas", "Juno", "Vesta",
        "Nodo Norte", "Nodo Sur", "Nodo Norte Verdadero", "Nodo Sur Verdadero",
        "Lilith Verdadera", "Parte de la Fortuna"
      ],
      "aspectos": {
        "tipos": [
          "conjuncion", "oposicion", "cuadratura", "trigono", "sextil",
          "quincuncio", "semicuadratura", "quintil"
        ],
        "orbes": {
          "planetas": {
            "conjuncion": 8.0, "cuadratura": 7.0, "oposicion": 8.0,
            "quincuncio": 3.0, "quintil": 2.0, "semicuadratura": 2.0,
            "sextil": 5.0, "trigono": 7.0
          },
          "puntos": {
            "conjuncion": 3.0, "cuadratura": 2.0, "oposicion": 3.0,
            "quincuncio": 1.5, "quintil": 1.0, "semicuadratura": 1.0,
            "sextil": 2.0, "trigono": 2.0
          }
        }
      }
    },
    "angulos_y_cuspides": {
      "ascendente": {
        "signo": "Escorpio",
        "grado": 16,
        "minuto": 20,
        "segundo": 52,
        "decimal": 226.3477,
        "formato": "16°20'52\""
      },
      "mc": {
        "signo": "Leo",
        "grado": 26,
        "minuto": 28,
        "segundo": 41,
        "decimal": 146.4781,
        "formato": "26°28'41\""
      },
      "descendente": {
        "signo": "Tauro",
        "grado": 16,
        "minuto": 20,
        "segundo": 52,
        "decimal": 46.3477,
        "formato": "16°20'52\""
      },
      "ic": {
        "signo": "Acuario",
        "grado": 26,
        "minuto": 28,
        "segundo": 41,
        "decimal": 326.4781,
        "formato": "26°28'41\""
      },
      "casas": [
        {
          "numero": 1,
          "cuspide": {
            "signo": "Escorpio",
            "grado": 16,
            "minuto": 20,
            "segundo": 52,
            "decimal": 226.3477,
            "formato": "16°20'52\""
          },
          "tamano_grados": 29.650037371424673
        }
      ]
    },
    "cuerpos": [
      {
        "nombre": "Sol",
        "posicion": {
          "signo": "Leo",
          "grado": 22,
          "minuto": 25,
          "segundo": 43,
          "decimal": 142.4287,
          "formato": "22°25'43\""
        },
        "casa": 9,
        "movimiento": "directo",
        "declinacion": {
          "degrees": 14,
          "direction": "+",
          "formatted": "14°02'18\"",
          "minutes": 2,
          "raw": 14.03842173051256,
          "seconds": 18
        },
        "dignidades": {
          "detriment": false,
          "exalted": false,
          "face_ruler": false,
          "fall": false,
          "formatted": ["Regente", "Regente de Triplicidad", "En su elemento de regencia"],
          "mutual_reception_exalted": false,
          "mutual_reception_face_ruler": false,
          "mutual_reception_ruler": false,
          "mutual_reception_term_ruler": false,
          "mutual_reception_triplicity_ruler": false,
          "peregrine": false,
          "ruler": true,
          "term_ruler": false,
          "triplicity_ruler": true
        },
        "score": 8,
        "in_sect": true,
        "out_of_bounds": false
      }
    ],
    "aspectos": {
      "tabla": [
        {
          "p1": "Ascendente",
          "p2": "Plutón",
          "tipo": "conjunción",
          "orbe": 8.0,
          "aplicativa": false
        },
        {
          "p1": "Sol",
          "p2": "Marte",
          "tipo": "cuadratura",
          "orbe": 7.0,
          "aplicativa": false
        }
      ]
    },
    "dignidades_y_recepciones": {
      "esencial": {
        "resumen": [
          "Sol: Regente (score: 8)",
          "Sol: Regente de Triplicidad (score: 8)",
          "Sol: En su elemento de regencia (score: 8)",
          "Luna: Peregrina (score: -5)",
          "Mercurio: Regente (score: 9)",
          "Mercurio: Exaltado (score: 9)"
        ]
      },
      "accidental": {
        "resumen": []
      },
      "puntajes": {
        "Sol": 8,
        "Luna": -5,
        "Mercurio": 9,
        "Venus": -5,
        "Marte": 1,
        "Júpiter": 4,
        "Saturno": 6,
        "Urano": -5,
        "Neptuno": -5,
        "Plutón": 5
      },
      "secta": "diurna"
    },
    "metadata": {
      "fase_lunar_natal": "Cuarto Menguante",
      "forma_carta": "Locomotora",
      "pesos": {
        "elementos": {
          "Agua": [3000001, 4000007, 4000011, 5000004, 5000005, 5000001],
          "Aire": [3000004, 4000002, 6000001, 6000003],
          "Fuego": [3000003, 4000001, 4000004, 6000002, 6000004, 6000007, 5000003],
          "Tierra": [3000002, 4000003, 4000006, 4000008, 4000009, 4000010, 6000010, 5000006]
        },
        "modalidades": {
          "Cardinal": [4000007, 4000008, 4000009, 4000010, 5000004, 5000001],
          "Fijo": [3000001, 3000002, 3000003, 3000004, 4000001, 4000004, 4000006, 4000011, 6000001, 6000002, 6000003, 6000004, 5000003, 5000005, 5000006],
          "Mutable": [4000002, 4000003, 6000007, 6000010]
        }
      }
    }
  }
}

Response Structure

The API returns a comprehensive natal chart analysis with the following main sections:

identidad: User's personal information (name, notes)
nacimiento: Birth data (date, time, location, coordinates)
referencias: Chart settings and calculation parameters
angulos_y_cuspides: Ascendant, MC, Descendant, IC, and all house cusps with detailed position data
cuerpos: Complete list of celestial objects (planets, asteroids, nodes, points) with:
- Position in zodiac (degrees, minutes, seconds, sign)
- House placement
- Movement direction and speed
- Declination data
- Detailed dignity information
- Essential and accidental dignity scores
- Sect and out-of-bounds status
aspectos: Complete aspect table with all planetary relationships
dignidades_y_recepciones: Essential and accidental dignity analysis with scores
metadata: Chart analysis including lunar phase, chart pattern, and element/modality distributions

🧪 Testing

Manual Testing with Docker

Once the container is running, you can test the API using any HTTP client:

Using Postman (Example)

Open Postman and create a new POST request
Set URL to: http://localhost:8080/api/v1/carta-natal
Set headers: Content-Type: application/json
Use the sample request body from the examples above
Send the request and verify the response structure

Using curl (Alternative)

curl -X POST http://localhost:8080/api/v1/carta-natal \
  -H "Content-Type: application/json" \
  -d @sample_request.json

Using Other HTTP Clients

You can use any HTTP client that supports POST requests with JSON payloads:

Insomnia
HTTPie
Python requests
JavaScript fetch API
Any programming language's HTTP library

Health Check

curl http://localhost:8080/health

Expected response:

{"status": "healthy", "service": "AstroLib API"}

🏗️ Architecture

Framework: Flask with Python 3.13
Astrology Engine: Immanuel Library
Containerization: Docker with multi-stage builds
HTTP Server: Gunicorn with 2 workers
Data Format: JSON with comprehensive validation

📄 License

This project is free and open source, licensed under AGPL-3.0. See the NOTICE file for additional attributions (Immanuel library) and credits.

📞 Support

For issues and questions: cristianbdev@gmail.com

Built with ❤️ by Cristianbdev for the astrology community

⬆ Back to top

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
app		app
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
main.py		main.py
requirements.txt		requirements.txt

Navigation Menu

Repository navigation

About

Repository files navigation

AstroLib API

🌟 Overview

🚀 Quick Start

Prerequisites

Installation with Docker

📋 API Reference

Endpoint

Request Schema

📝 Examples

Sample Request

Sample Response

Response Structure

🧪 Testing

Manual Testing with Docker

Using Postman (Example)

Using curl (Alternative)

Using Other HTTP Clients

Health Check

🏗️ Architecture

📄 License

📞 Support

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AstroLib API

🌟 Overview

🚀 Quick Start

Prerequisites

Installation with Docker

📋 API Reference

Endpoint

Request Schema

📝 Examples

Sample Request

Sample Response

Response Structure

🧪 Testing

Manual Testing with Docker

Using Postman (Example)

Using curl (Alternative)

Using Other HTTP Clients

Health Check

🏗️ Architecture

📄 License

📞 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages