Getting Started

Introduction

The Meridian Ephemeris API is a comprehensive astronomical computation platform providing:

• Natal Charts - Birth charts with planets, houses, aspects, and hermetic lots
• Progressed Charts - Secondary progressions with Naibod arc
• Transits - Transit aspects and timing calculations
• Returns - Solar and lunar return charts with precise timing
• Predictive Astrology - Transit searches, sign ingresses, planetary timing
• Specialized Calculations - Fixed stars, midpoints, hermetic lots, lunar phases
• Location Services - Geocoding and timezone resolution
• Chart Visualization - SVG wheel chart generation with custom styling
• Metadata & Utilities - Configuration schemas, health checks, API documentation

Quick Start

1. Create an Account

Start your 14-day trial at /start. Complete secure checkout and we’ll email you a sign-in link.

2. Sign In and Access Your Dashboard

After signing in, you'll be taken to your Dashboard. From there you can:

• Test API endpoints in Endpoints
• Manage your API Keys
• Manage your Account

3. Make Your First Request

All API requests require authentication via an API key or a JWT. Here's an example natal chart request:

curl -X POST https://api.astromcp.io/ephemeris/natal-chart \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "name": "John Doe",
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": { "decimal": 40.7128 },
        "longitude": { "decimal": -74.006 },
        "timezone": { "iana_name": "America/New_York" }
      }
    },
    "configuration": {
      "house_system": "P",
      "zodiac_type": "tropical",
      "coordinate_system": "geocentric"
    }
  }'

4. Understand the Response

The API returns comprehensive chart data:

{
  "success": true,
  "subject": {
    "name": "John Doe",
    "datetime": "1990-06-15T14:30:00",
    "julian_day": 2448058.27083,
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone_name": "America/New_York"
  },
  "planets": {
    "sun": {
      "longitude": 84.25,
      "latitude": 0.0,
      "distance": 1.016,
      "speed": 0.955,
      "sign": "Gemini",
      "degree_in_sign": 24.25,
      "retrograde": false
    },
    "moon": { ... },
    "mercury": { ... }
  },
  "houses": {
    "1": { "cusp": 245.67, "sign": "Sagittarius" },
    "2": { ... }
  },
  "angles": {
    "asc": { "longitude": 245.67, "sign": "Sagittarius" },
    "mc": { "longitude": 170.23, "sign": "Virgo" }
  },
  "aspects": [
    {
      "planet1": "sun",
      "planet2": "moon",
      "aspect": "trine",
      "orb": 2.5,
      "applying": true
    }
  ],
  "hermetic_lots": {
    "fortune": { "longitude": 120.5, "sign": "Leo" }
  }
}

Request Format Reference

Subject (Required)

{
  "subject": {
    "name": "Subject Name",
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": { "decimal": 40.7128 },
      "longitude": { "decimal": -74.006 },
      "timezone": { "iana_name": "America/New_York" }
    }
  }
}

Configuration (Optional)

| Field | Values | Default | |-------|--------|---------| | house_system | P (Placidus), K (Koch), W (Whole Sign), E (Equal), C (Campanus), R (Regiomontanus) | P | | zodiac_type | tropical, sidereal | tropical | | coordinate_system | geocentric, heliocentric, topocentric | geocentric | | object_set | classic_core, modern, extended, all | classic_core |

Response Options (Optional)

{
  "options": {
    "include_aspects": true,
    "include_hermetic_lots": true,
    "verbosity": "detailed"
  }
}

Next Steps

• Core Endpoints – Full endpoint reference
• Authentication – JWT authentication details
• Error Handling – Error codes and handling
• MCP Integration – AI/LLM integration

Using Endpoints

The easiest way to explore the API is Endpoints. It handles authentication automatically and lets you:

• Configure birth data with visual form
• Select house systems and options
• View formatted JSON responses
• Copy responses for use in your applications