API Endpoints Overview

Complete guide to all Meridian Ephemeris API endpoints organized by category.

Base URL

https://api.astromcp.io

All endpoints require authentication via one of the supported auth modes:

Authorization: Bearer YOUR_JWT_TOKEN

X-API-Key: YOUR_API_KEY

Endpoint Categories

The Meridian Ephemeris API organizes endpoints into logical categories for easy navigation.

📊 Core Ephemeris

Fundamental chart calculation endpoints for natal, progressed, and relocated charts.

| Endpoint | Method | Description | |----------|--------|-------------| | /ephemeris/natal-chart | POST | Calculate natal (birth) charts | | /ephemeris/relocation | POST | Relocate chart to different coordinates | | /ephemeris/progressed | POST | Calculate secondary progressed charts | | /ephemeris/natal/batch | POST | Batch calculate multiple natal charts | | /ephemeris/house-systems | GET | List all supported house systems | | /ephemeris/supported-objects | GET | List all supported celestial bodies | | /ephemeris/supported-metadata | GET | Get supported metadata lookups and enums |

View Natal Charts Documentation →

� Comparative Astrology

Synastry, composite charts, and transit overlays.

| Endpoint | Method | Description | |----------|--------|-------------| | /comparative/synastry | POST | Calculate inter-aspects between two charts | | /comparative/composite | POST | Calculate composite midpoint chart | | /comparative/natal-transits | POST | Natal chart with current transits overlay |

�🔮 Predictive Astrology

Transit timing, sign ingresses, returns, and event forecasting.

| Endpoint | Method | Description | |----------|--------|-------------| | /predictive/transits/planet-to-degree | POST | When planets cross specific degrees | | /predictive/transits/sign-ingresses | POST | When planets enter new signs | | /predictive/transits/search | POST | Search for transit aspects over time ranges | | /predictive/transit-chart | POST | Full transit chart snapshot at a moment | | /predictive/returns | POST | Calculate planetary return timing near a target datetime |

View Predictive Documentation →

🧮 Calculations

Specialized calculation endpoints for fixed stars, midpoints, hermetic lots, and lunar phases.

| Endpoint | Method | Description | |----------|--------|-------------| | /ephemeris/fixed-stars | POST | Fixed star positions for a datetime | | /ephemeris/midpoints | POST | Calculate planetary midpoints (short/long arc) | | /ephemeris/hermetic-lots | POST | Fortune Suite hermetic lots (7 lots) | | /ephemeris/lunar-phase | POST | Lunar phase and illumination percentage | | /ephemeris/house-cusps | POST | House cusps (granular) | | /ephemeris/angles-points | POST | Angles + points (granular) | | /ephemeris/uranian-points | POST | Uranian (Hamburg) points (granular) | | /ephemeris/dignities | POST | Essential dignities (granular) | | /ephemeris/moon/aspects | GET | Moon aspects at a datetime | | /ephemeris/moon/ingresses | GET | Moon sign ingresses | | /ephemeris/moon/phase | GET | Current moon phase details | | /ephemeris/moon/void-of-course | GET | Void-of-course moon periods |

View Calculations Documentation →

🎨 Visualization

SVG wheel chart rendering and style discovery.

| Endpoint | Method | Description | |----------|--------|-------------| | /ephemeris/charts/styles | GET | List available chart styles | | /ephemeris/charts/wheel | POST | Generate chart wheel (SVG/PNG) |

View Visualization Documentation →

🗺️ Location Services

Geocoding, autocomplete, and reverse geocoding services.

| Endpoint | Method | Description | |----------|--------|-------------| | /location/autocomplete | GET | Search locations with query parameter | | /location/reverse | GET | Convert coordinates to city/timezone |

View Location Documentation →

🌐 Timezone Services

IANA timezone lookup and UTC offset calculation with DST handling.

| Endpoint | Method | Description | |----------|--------|-------------| | /timezone/lookup | POST | Get IANA timezone for coordinates | | /timezone/offset | POST | Calculate UTC offset with DST |

View Timezone Documentation →

🔧 Metadata & Utilities

API metadata, configuration schemas, health checks, and developer tools.

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | API version and service info | | /meta/openapi.json | GET | OpenAPI specification | | /meta/version | GET | API version info | | /ephemeris/schemas/natal-request | GET | Natal chart request schema | | /ephemeris/schemas/natal-response | GET | Natal chart response schema | | /ephemeris/house-systems | GET | List all supported house systems | | /ephemeris/supported-objects | GET | List all supported celestial bodies | | /health | GET | Basic health check | | /health/detailed | GET | Detailed system metrics | | /ephemeris/health | GET | Ephemeris service health |

View Metadata Documentation →

Quick Start Examples

Calculate a Natal Chart

curl -X POST https://api.astromcp.io/ephemeris/natal-chart \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "name": "Example Person",
      "birth_datetime": { "iso": "1990-06-15T14:30:00" },
      "birth_location": {
        "latitude": { "decimal": 40.7128 },
        "longitude": { "decimal": -74.0060 },
        "timezone": { "iana_name": "America/New_York" }
      }
    }
  }'

Search for a Location

curl "https://api.astromcp.io/location/autocomplete?query=Paris&limit=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get a Transit Chart Snapshot

curl -X POST https://api.astromcp.io/predictive/transit-chart \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "name": "Transit Moment",
      "birth_datetime": { "iso": "2024-12-08T12:00:00Z" },
      "birth_location": {
        "latitude": { "decimal": 40.7128 },
        "longitude": { "decimal": -74.0060 },
        "timezone": { "iana_name": "America/New_York" }
      }
    }
  }'

Response Format

All endpoints return JSON in this format:

{
  success: boolean;
  data?: any;  // Response data (if success=true)
  error?: string;  // Error type (if success=false)
  message?: string;  // Human-readable message
  details?: Record<string, any>;  // Additional context
}

Next Steps

Authentication Guide - Get your JWT token
Getting Started - Your first API call
Error Handling - Handle errors gracefully
Rate Limits - Understand usage limits

Need Help?