# Minglion

> Eastern & Western divination as structured JSON output that AI can actually read.

Minglion is an API service that provides structured divination data (JSON) designed for LLMs and AI applications. No more blurry screenshots or hallucinated chart readings — get precise, machine-readable astrology and divination data.

## API Modules

### Tarot API
- Endpoint: POST /api/v1/tarot/draw
- Draw tarot cards with multiple spread types (one-card, three-card, Celtic Cross)
- Returns card names, orientations (upright/reversed), positions, meanings, and reading summaries
- Supports bilingual output (English / Chinese)

### I Ching API
- Endpoint: POST /api/v1/iching/cast
- Cast hexagrams using random or three-coin methods
- Returns original hexagram, transformed hexagram, changing lines, judgment, image, and line texts
- Built-in database of all 64 hexagrams

### Bazi (Four Pillars) API
- Endpoint: POST /api/v1/bazi/chart
- Calculate Four Pillars of Destiny from birth date/time
- Returns year/month/day/hour pillars, heavenly stems, earthly branches, ten gods, five element analysis
- Includes 29 special stars and Da Yun (major fortune) cycles

### Zi Wei Dou Shu (Purple Star Astrology) API
- Endpoint: POST /api/v1/ziwei/chart
- Generate complete twelve-palace chart
- Returns palace arrangements, main stars, auxiliary stars, four transformations (Lu/Quan/Ke/Ji)
- Includes major period (Da Xian) and annual fortune analysis

### Western Astrology API
- Endpoint: POST /api/v1/astro/natal
- Calculate natal chart from birth date, time, and location
- Returns planet positions (sign + degree), twelve houses, and aspect analysis
- Supports major aspects: conjunction, sextile, square, trine, opposition

### Numerology API
- Endpoint: POST /api/v1/numerology/life-path
- Calculate Life Path Number from birth date (1-9, 11, 22)
- Returns traits, life purpose, challenges, and personalized advice

## Authentication

All API endpoints require a Bearer token. Get your free API key at https://minglion.com (sign in with Google).

Header: `Authorization: Bearer YOUR_API_KEY`

## Response Format

All responses are structured JSON:
```json
{
  "status": "success",
  "data": { ... },
  "meta": { "credits_used": 1, "lang": "en" }
}
```

## Key Features

- **AI-Friendly**: Structured JSON output ready for ChatGPT, Claude, Gemini, and other LLMs
- **Bilingual**: Built-in English and Chinese (Traditional/Simplified) responses via `?lang=` parameter
- **Privacy-First**: API keys stored as hashes only; birth data never used for model training
- **Free Tier**: All modules available for free with generous rate limits

## Links

- Website: https://minglion.com
- API Documentation: https://minglion.com/reference
- Privacy Policy: https://minglion.com/privacy
- Terms of Service: https://minglion.com/terms