🔮⚡ High-fidelity Human Design calculation engine — birth-chart analytics, BodyGraph visualization, and Group/Penta dynamics via a FastAPI service.
Human Design API is a high-performance Python service that powers modern Human Design applications. It serves as a comprehensive backend engine that:
- Calculates core and deep Human Design metrics from birth data (Earth, Moon, Nodes, Planets, Gates, Lines, Color, Tone, Base).
- Resolves birth locations to precise geocoordinates and timezones automatically.
- Visualizes results by generating beautiful, high-quality BodyGraph images on-the-fly.
Whether you are building a mobile app, a professional dashboard, or a personal research tool, this API provides the rigorous astrological data and visual assets you need — all containerized for easy deployment.
- V2 Calculate API: High-performance
POST /v2/calculatewith semantic enrichment, Dream Rave, and Global Cycle support. - High-Fidelity Maia Matrix v2: Advanced relational analysis with planetary triggers, nodal resonance, and sub-circuit details.
- Penta Analysis 2.0: Enhanced Group Dynamics (3–5 people) via the
/analyze/pentaendpoint (Sovereign Standard). - Maia-Penta Hybrid Analysis: Flagship
POST /analyze/maia-pentaendpoint for professional composite + group dynamics in one request. - Grounded 10x Interpretation: Consultant-grade, psychology-grounded reports with zero-jargon semantic output.
- Global Performance (Sub-20ms): Integrated
TimezoneFindersingleton and geocoding bypass for 100× lower latency. - Coordinate Support: All endpoints accept optional
latitude/longitudeto bypass geocoding for maximum precision and speed. - FastAPI Backend: High-performance, async-ready Python web framework.
- Precise Calculations:
pyswissephfor Swiss Ephemeris accuracy;geopy/timezonefinderfor location and timezone resolution. - BodyGraph Visualization: High-fidelity BodyGraph charts in PNG, SVG, and JPG via
/bodygraph. - Comprehensive Chart Data: Energy Type, Strategy, Authority, Profile, Incarnation Cross, Variables, Age, Western Zodiac, and full Planetary/Gate positions.
| Feature | Legacy V1 | Flagship V2 |
|---|---|---|
| Request Type | GET (Limited) | POST (Scalable JSON) |
| Performance | Standard | High (Coordinate Bypass) |
| Output Control | Fixed Response | Selective (Include/Exclude) |
| Dream Rave | ❌ No | ✅ Included |
| Global Cycles | ❌ No | ✅ Included |
| Semantic Layer | Basic | ✅ Deep Enrichment |
| Variables/PHS | Partial | ✅ Full Schema Support |
- Docker: Installed and running. Download from Docker's official website.
- Docker Compose: Usually bundled with Docker Desktop. Verify with
docker-compose --version.
git clone https://github.com/dturkuler/humandesign_api.git
cd humandesign_api
cp .env_example .env # then set HD_API_TOKEN
docker-compose up --build -dThe API is then accessible at http://localhost:9021. Verify with docker ps (look for the humandesignapi container).
pip install -e .
uvicorn humandesign.api:app --host 0.0.0.0 --port 9021Note
The .env file stores your API token (HD_API_TOKEN). Keep it secret — it is gitignored.
The API exposes calculation, visualization, and analysis endpoints. A minimal V2 request:
curl -X POST "http://localhost:9021/v2/calculate" \
-H "Authorization: Bearer your_secret_token_here" \
-H "Content-Type: application/json" \
-d '{"year": 1990, "month": 7, "day": 15, "hour": 14, "minute": 30, "place": "London, UK"}'Calculates comprehensive Human Design features from birth information.
| Name | Type | Description | Required |
|---|---|---|---|
year |
integer |
Birth year (e.g., 1990) |
Yes |
month |
integer |
Birth month (e.g., 7) |
Yes |
day |
integer |
Birth day (e.g., 15) |
Yes |
hour |
integer |
Birth hour (24h, e.g., 14) |
Yes |
minute |
integer |
Birth minute (e.g., 30) |
Yes |
second |
integer |
Birth second (default 0) |
No |
place |
string |
Birth place (e.g., London, UK) |
Yes |
Example Response (condensed):
{
"general": {
"birth_date": "1990-07-15T13:30:00Z",
"age": 35,
"energy_type": "Projector",
"strategy": "Wait for the Invitation",
"inner_authority": "Solar Plexus",
"inc_cross": "The Right Angle Cross of the Maya (2)",
"profile": "3/5: Martyr Heretic",
"definition": "Split Definition"
},
"gates": { },
"channels": { "Channels": [ { "channel": "30/41: The Channel of Recognition..." } ] }
}Generates a visual BodyGraph chart image from birth information. Accepts the same birth parameters plus:
| Name | Type | Description | Default |
|---|---|---|---|
fmt |
string |
Image format: png, svg, jpg, jpeg |
png |
curl -X GET "http://localhost:9021/bodygraph?year=1990&month=7&day=15&hour=14&minute=30&place=London%2C%20UK&fmt=png" \
-H "Authorization: Bearer your_secret_token_here" -o bodygraph.pngCalculates the "Weather of the Day" via a composite of birth data and current planetary transit. Requires birth data plus transit_year, transit_month, transit_day.
curl -X GET "http://localhost:9021/transits/daily?year=1990&month=7&day=15&hour=14&minute=30&place=London%2C%20UK&transit_year=2025&transit_month=12&transit_day=22" \
-H "Authorization: Bearer your_secret_token_here"Calculates the "Yearly Theme" (Solar Return). Requires birth data plus sr_year_offset (years after birth, default 0).
curl -X GET "http://localhost:9021/transits/solar_return?year=1990&month=7&day=15&hour=14&minute=30&place=London%2C%20UK&sr_year_offset=0" \
-H "Authorization: Bearer your_secret_token_here"Detailed pairwise composite analysis for exactly two people.
{
"person1": { "place": "Berlin, Germany", "year": 1985, "month": 6, "day": 15, "hour": 14, "minute": 30 },
"person2": { "place": "Munich, Germany", "year": 1988, "month": 11, "day": 22, "hour": 9, "minute": 15 }
}curl -X POST "http://localhost:9021/analyze/composite" \
-H "Authorization: Bearer your_secret_token_here" \
-H "Content-Type: application/json" -d @payload.jsonResponse:
{
"participants": ["person1", "person2"],
"new_channels": [ { "gate": 59, "ch_gate": 6, "meaning": ["Mating", "A d. focused on reproduction"] } ],
"duplicated_channels": [],
"new_chakras": ["SolarPlexus"],
"composite_chakras": ["Ajna", "Throat", "G_Center", "SolarPlexus", "Sacral", "Root"]
}Composite Human Design matrix (Relationship Mechanics) for two or more people.
curl -X POST "http://localhost:9021/analyze/compmatrix" \
-H "Authorization: Bearer your_secret_token_here" \
-H "Content-Type: application/json" -d @payload.jsonGroup Dynamics (Penta) using the Sovereign Standard (consultant-level interpretation).
{
"group_type": "family",
"participants": {
"Person A": { "place": "City, Country", "year": 1985, "month": 6, "day": 15, "hour": 14, "minute": 30 },
"Person B": { }
}
}curl -X POST "http://localhost:9021/analyze/penta" \
-H "Authorization: Bearer your_secret_token_here" \
-H "Content-Type: application/json" -d @penta_v2_payload.json.
├── .env_example
├── CHANGELOG.md
├── LICENSE
├── README.md
├── docker-compose.yml
├── Dockerfile
├── openapi.yaml
├── pyproject.toml
└── src/
└── humandesign/
├── api.py # FastAPI Application Entry
├── data/ # Static layout and hd data
├── features/ # Core Rave Engine logic
├── routers/ # API Route definitions
├── schemas/ # Pydantic validation models
├── services/ # Business logic services
└── utils/ # Utilities (Astrology, Versioning, etc.)
For comprehensive details, industrial-standard references, and runnable examples, see API_DOCUMENTATION.md.
The project ships an OpenAPI 3.0 specification (openapi.yaml) describing endpoints, parameters, responses, and schemas.
- Visualize: Use a VS Code "Swagger Viewer" extension, or paste into the Swagger Editor.
- Import into Postman:
Import→ drag-dropopenapi.yaml; a pre-configured collection is generated. - Generate Clients: Use
openapi-generatorfor Python, JavaScript, Java, and more.
This project is dual-licensed:
| Tier | Price | API Access | Credits / mo | Target Feature Set |
|---|---|---|---|---|
| Hobbyist | $0 | V1 Only | 50 | Legacy Calculations |
| Startup | $49/mo | V1 + V2 | 20,000 | V2 Flagship + Interpretation |
| Business | $149/mo | V1 + V2 | 150,000 | Penta, Matrix, White-Label |
| Enterprise | $499+/mo | V1 + V2 | Custom | Unlimited Use, SLA, Support |
- V2 Flagship Engine: Dream Rave, Global Cycles, and Selective Output Masking are restricted to paid tiers.
- Startup Tier: Unlocks V2 access and the standard 10x Interpretation engine.
- Business Tier (Professional): Unlocks Group Penta Analysis, Maia-Matrix Relational Analytics, and White-Label BodyGraphs (no watermark).
- Enterprise Tier: Full distribution rights for multiple domains, custom branding, and 99.9% uptime SLA.
Commercial self-hosted licenses start at $1,000/year. Contact: dogan.turkuler@gmail.com | https://devaible.com
Contributions are welcome. Please open an issue or pull request on GitHub. For development setup, clone the repo, create a .env from .env_example, and run docker-compose up --build -d.
Documentation generated for Human Design API v4.0.3