Structured Horoscope API

This beta endpoint compares a natal chart with one transit instant and returns deterministic interpretation fields that your application can render in its own voice.

Beta contract

Output fields may expand while the endpoint is in beta. It does not call a language model and does not return horoscope prose. The current rules keep major aspects only and expose tone, intensity, planetary nature, sect fields, and a stable summary key.

Endpoint

POST https://api.cosmicephemeris.com/api/astro/horoscope

Authenticate with Authorization: Bearer <API_KEY> from your server.

Request fields

  • birth.date, birth.time, birth.lat, and birth.lon are required.
  • birth.timezone accepts an IANA name and defaults to UTC.
  • transitDate defaults to the current UTC date.
  • transitTime defaults to 12:00; top-level timezone defaults to UTC.
  • zodiac defaults to tropical. In sidereal mode, ayanamsa defaults to lahiri.

Times must use HH:MM or HH:MM:SS. A local time that is skipped or repeated during a daylight-saving or other clock change returns 400; send the known UTC date and time with timezone: "UTC" to identify the intended instant without guessing an hour.

Example request

{
  "birth": {
    "date": "1990-01-01",
    "time": "12:00",
    "timezone": "America/New_York",
    "lat": 40.7128,
    "lon": -74.006
  },
  "transitDate": "2025-01-01",
  "transitTime": "12:00",
  "timezone": "America/New_York"
}

Response shape

The following is abbreviated from the request above. Signal values depend on the requested instants.

{
  "type": "horoscope",
  "input": {
    "birth": { "...": "submitted birth fields" },
    "transitDate": "2025-01-01",
    "zodiac": "tropical",
    "ayanamsa": "lahiri"
  },
  "interpretation": {
    "summary": {
      "overall_tone": "challenging",
      "intensity": 0.88
    },
    "transits": [
      {
        "planet": "Sun",
        "planet_nature": "luminary",
        "planet_sect": "day",
        "chart_sect": "day",
        "aspect": "Conjunction",
        "natal_point": "Sun",
        "house": null,
        "house_topics": [],
        "tone": "intensifying",
        "intensity": 1,
        "tradition": ["hellenistic", "western"],
        "summary_key": "sun_conjunction_sun"
      }
    ]
  }
}

Current limits

  • The public calculation window is 1900-01-01 through 2050-12-31.
  • The rules emit structured signals only; your product owns prose and editorial meaning.
  • chart_sect is calculated from the natal location and instant: day when the apparent Sun's center is above the geometric horizon, night otherwise. The calculation uses zero elevation and no atmospheric refraction; it is not a sunrise/sunset timetable.
  • House attribution is not yet attached to transit signals and currently returns null.
  • This is a standard billable endpoint under the account's monthly request quota.

Errors

  • 400 invalid fields, timezone, zodiac, ayanamsa, or date range
  • 401 missing or invalid API key
  • 429 monthly quota or edge rate limit reached
  • 502 calculation engine unavailable; 504 calculation timed out
  • 503 service concurrency limit; retry according to Retry-After when present