WESTERN ASTROLOGY · JSON REST API

Astrology Transits API

Evaluate the moving sky against a person’s birth chart at a specific moment. The result separates transiting positions from the natal chart and identifies the cross-aspects between them.

AvailablePOST /v1/astrology/transits

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Compare transiting planets with a natal chart at an explicit instant. Return cross-aspects, separations, orbs and localized interpretation in JSON.

01

An explicit offset-aware transit instant

02

Ten transiting planetary positions

03

Natal chart using your selected house system

04

Transit-to-natal major aspects with numerical orbs

Send

  • A complete birth object for the natal chart
  • at as an ISO 8601 timestamp with Z or an explicit UTC offset
  • Optional whole_sign, equal or placidus houses and a supported locale

Receive

  • at and transiting_planets
  • natal_chart with its own positions and houses
  • cross_aspects and fact-linked transit/natal interpretation
FROM THE NUMERICAL RESULT

See the calculated chart.

The original renderer uses the exact positions in this example. These are computed charts, not stock diagrams. JSON remains the authoritative source.

Natal component from the Astrology Transits API computed fixture
Natal component. Download SVG ↗
INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/astrology/transits
{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  },
  "at": "2026-11-17T12:00:00Z"
}
Response JSON · selected fields
{
  "request_id": "0aa6ee8b9bdafa831e2669c25dd65565",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "at": "2026-11-17T12:00:00Z",
    "transiting_planets": {
      "sun": {
        "longitude": 235.14950301,
        "latitude": 0.00005741,
        "distance_au": 0.9887512033,
        "sign": "scorpio"
      },
      "moon": {
        "longitude": 325.24399438,
        "latitude": 0.00880168,
        "distance_au": 0.0026572683,
        "sign": "aquarius"
      },
      "mercury": {
        "longitude": 216.29313258,
        "latitude": 2.37186494,
        "distance_au": 0.9102118725,
        "sign": "scorpio"
      },
      "venus": {
        "longitude": 203.10287643,
        "latitude": -0.88450141,
        "distance_au": 0.3435421732,
        "sign": "libra"
      },
      "mars": {
        "longitude": 146.43535722,
        "latitude": 1.96940254,
        "distance_au": 1.2944937627,
        "sign": "leo"
      },
      "jupiter": {
        "longitude": 145.98863855,
        "latitude": 0.74953955,
        "distance_au": 5.2438458128,
        "sign": "leo"
      },
      "saturn": {
        "longitude": 8.42093574,
        "latitude": -2.63699658,
        "distance_au": 8.7157165538,
        "sign": "aries"
      }
    },
    "natal_chart": {
      "birth_time_known": true,
      "at": "1990-05-21T12:30:00Z",
      "planets": {
        "sun": {
          "longitude": 60.19554186,
          "latitude": 0.00015523,
          "distance_au": 1.0121680489,
          "sign": "gemini"
        },
        "moon": {
          "longitude": 18.08236232,
          "latitude": 4.67747445,
          "distance_au": 0.0024294565,
          "sign": "aries"
        },
        "mercury": {
          "longitude": 38.664821,
          "latitude": -3.37497387,
          "distance_au": 0.6700853983,
          "sign": "taurus"
        },
        "venus": {
          "longitude": 19.7137408,
          "latitude": -1.9474912,
          "distance_au": 1.0821255365,
          "sign": "aries"
        }
      },
      "houses": {
        "system": "whole_sign",
        "ascendant": 158.31543091,
        "midheaven": 64.64823285,
        "cusps": [
          150
        ]
      },
      "aspects": [
        {
          "body1": "mercury",
          "body2": "uranus",
          "aspect": "trine",
          "angle": 120
        },
        {
          "body1": "moon",
          "body2": "venus",
          "aspect": "conjunction",
          "angle": 0
        }
      ],
      "warnings": []
    },
    "cross_aspects": [
      {
        "body1": "sun",
        "body2": "saturn",
        "aspect": "sextile",
        "angle": 60
      },
      {
        "body1": "saturn",
        "body2": "uranus",
        "aspect": "square",
        "angle": 90
      }
    ]
  },
  "interpretation": {
    "locale": "en",
    "kind": "astrology/transits",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 57,
      "selected_facts": 57,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "astrology/transits.transiting_planets.sun",
        "title": "Transiting positions · Sun · Scorpio",
        "text": "Context: Transiting positions. Sun · Scorpio · 25.1495° within the sign. Zodiac: tropical. Symbolic focus: self-expression and direction. Examine trust and boundaries before seeking greater intensity. Reference time: 2026-11-17T12:00:00Z.",
        "source": {
          "longitude": 235.14950301,
          "latitude": 0.00005741,
          "distance_au": 0.9887512033,
          "sign": "scorpio",
          "sign_degree": 25.14950301,
          "speed_deg_per_day": 1.0080288,
          "retrograde": false,
          "id": "astrology/transits.transiting_planets.sun",
          "type": "astro_placement",
          "planet": "sun",
          "frame": "tropical",
          "at": "2026-11-17T12:00:00Z",
          "context": [
            "transiting_planets"
          ]
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 5
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/astrology/transits' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: transits-api-example-001' \
+  --data '{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  },
  "at": "2026-11-17T12:00:00Z"
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • A daily transit screen evaluated at your chosen moment
  • Personalized notifications from your own selection rules
  • Comparing astrological context across product sessions

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • This endpoint evaluates one instant; it does not find every exact aspect crossing in a date range.
  • The chart graphic below shows the natal component, not a transit biwheel. Both numerical components are present in the full JSON.
  • Interpretation is symbolic and does not promise that an event will occur.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Does a transit response find exact event times?

No. It returns a snapshot at the requested instant. Use the aspect calendar for exact transit-to-natal crossings, or daily forecast for one sample per local day.

What time zone does at use?

at must include its UTC offset. The birth object independently uses an IANA time zone for the original local birth time.

Are transit and natal facts mixed in the reading?

The response and interpretation retain separate natal and transiting contexts, with source fact identifiers so your application can trace each paragraph.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 5 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API