Maphrodite API

Overview

The Maphrodite Engine is a stateless astrocartography calculation service. It returns planetary line GeoJSON vectors, city compatibility scores, and transit-based timing intelligence — with retrograde detection, lunar phases, and eclipse awareness. Zero PII is stored; all calculations are performed in-memory and discarded after the response.

All requests are authenticated via the X-API-KEY header. To obtain a key, email [email protected].

Base URL

https://api.maphrodite.com

Authentication

Pass your API key as a request header on every call:

X-API-KEY: YOUR_API_KEY

Endpoints

POST /v1/calculate-lines

Returns MC/IC and ASC/DSC GeoJSON vectors for all 10 planetary bodies (Sun through Pluto) across the globe, calculated from a natal birth position.

Request body

Field	Type	Description
date	string	Birth date in YYYY-MM-DD format
time	string	Birth time in HH:MM (24 h, local)
lat	number	Birth latitude (decimal degrees)
lon	number	Birth longitude (decimal degrees)

Example request

curl -X POST "https://api.maphrodite.com/v1/calculate-lines" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "date": "1990-01-15",
    "time": "14:30",
    "lat": 51.50,
    "lon": -0.12
  }'

Returns GeoJSON planetary line vectors for all bodies.

---

POST /v1/score-city

Calculates a 0–100 compatibility score for a specific location, with categorical breakdowns across career, love, growth, and health.

Request body

Field	Type	Description
date	string	Birth date (YYYY-MM-DD)
time	string	Birth time (HH:MM)
lat	number	Birth latitude
lon	number	Birth longitude
city_lat	number	Target city latitude
city_lon	number	Target city longitude
city_name	string	City label (returned in response)

Example request

curl -X POST "https://api.maphrodite.com/v1/score-city" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "date": "1990-01-15",
    "time": "14:30",
    "lat": 51.50,
    "lon": -0.12,
    "city_lat": 35.68,
    "city_lon": 139.65,
    "city_name": "Tokyo"
  }'

Returns an overall compatibility score and per-category breakdowns (career, love, growth, health).

---

POST /v1/score-city-timing

Advanced transit timing endpoint. Combines the natal chart with real-time planetary movements, retrograde detection, lunar phases, and eclipse proximity to surface optimal travel windows and best days within a date range.

Request body

Field	Type	Description
date	string	Birth date (YYYY-MM-DD)
time	string	Birth time (HH:MM)
lat	number	Birth latitude
lon	number	Birth longitude
city_lat	number	Target city latitude
city_lon	number	Target city longitude
city_name	string	City label
visit_start	string	Start of visit window (YYYY-MM-DD)
visit_end	string	End of visit window (YYYY-MM-DD)
mode	string	travel | relocation | work | love

Example request

curl -X POST "https://api.maphrodite.com/v1/score-city-timing" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "date": "1990-05-20",
    "time": "14:30",
    "lat": 51.5074,
    "lon": -0.1278,
    "city_lat": 48.8566,
    "city_lon": 2.3522,
    "city_name": "Paris",
    "visit_start": "2026-06-01",
    "visit_end": "2026-06-07",
    "mode": "travel"
  }'

Example response

{
  "overall_score": 82.3,
  "birth_chart_score": 75.5,
  "transit_bonus": 6.8,
  "timing_insight": "Exceptional timing! Venus forms a harmonious trine...",
  "best_days": [
    {
      "date": "2026-06-03",
      "score": 92.3,
      "insight": "Venus trine natal Sun (exact aspect)",
      "lunar_phase": "New Moon"
    }
  ],
  "active_transits": [...],
  "category_scores": {
    "career": 80.1,
    "love": 88.2,
    "growth": 79.5
  }
}

Transit Intelligence (v1.4.0)

The /v1/score-city-timing endpoint includes three layers of transit analysis:

Feature	Detail
Retrograde detection	Mercury, Venus, and Mars retrograde periods tracked with automatic potency adjustments and plain-language guidance
Lunar phases	All 8 moon phases returned with mode-specific interpretations (e.g. New Moon favours travel starts; Full Moon advises against relocations)
Eclipse detection	Solar and lunar eclipse proximity with intensity ratings; flags transformative windows near eclipse dates

Technical Specifications

Attribute	Value
Ephemeris	Swiss Ephemeris (JPL HORIZONS data, same as NASA)
Precision	0.001 arcsecond
Date range	±13,000 years
Planetary bodies	Sun through Pluto (10 bodies)
Architecture	Fully stateless — no PII stored; all data processed in-memory
Compliance	GDPR / CCPA
Transport	TLS 1.3
Avg. response time	~120 ms
Uptime SLA	99.97%
Deployment	Global edge
Current stable	v1.4.0

Enterprise

The Maphrodite Engine powers travel platforms and consumer apps worldwide. Enterprise agreements include custom rate limits, dedicated integration support, and architecture consultation. To discuss a commercial integration, email [email protected].

API Key Access

The API is not publicly open. To request a key and access to full interactive documentation, contact [email protected]. Once issued, authenticated API docs are available at api.maphrodite.com.