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.astroapi.io/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.

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.
  • 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