WESTERN ASTROLOGY · JSON REST API

Planetary Positions API

Request calculation data without a prose reading. This endpoint uses the same Western chart calculation as the natal endpoint, with a lower credit cost and interpretation set to null.

AvailablePOST /v1/astrology/positions

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

BUILD AROUND THE DATA

What this API provides.

Get tropical planetary longitudes, zodiac signs, speeds and retrograde flags as JSON. Inspect a computed sample from the JPL DE440s engine.

01

Sun, Moon and eight planets through Pluto

02

Apparent geocentric longitudes, sign degrees and finite-difference speeds

03

Explicit direct or retrograde motion

04

The current v1 data object also contains chart houses and aspects when time is known

Send

  • Use birth for the date, local time, IANA time zone and coordinates to evaluate
  • Select the supported tropical zodiac and optional house system
  • Choose locale for the response envelope; no rule interpretation is generated

Receive

  • data.planets with numeric positions and motion
  • Available houses and aspects from the shared chart engine
  • interpretation: null, plus profile metadata and uncertainty warnings
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.

Calculated zodiac positions from the Planetary Positions API computed fixture
Calculated zodiac positions. 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/positions
{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  }
}
Response JSON · selected fields
{
  "request_id": "3d50750df880a04855d0b6cac57eee82",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "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"
      },
      "mars": {
        "longitude": 352.79743592,
        "latitude": -1.79049776,
        "distance_au": 1.4212788567,
        "sign": "pisces"
      },
      "jupiter": {
        "longitude": 100.70255878,
        "latitude": 0.15100962,
        "distance_au": 5.9296233345,
        "sign": "cancer"
      },
      "saturn": {
        "longitude": 295.11911348,
        "latitude": 0.14808899,
        "distance_au": 9.3994642274,
        "sign": "capricorn"
      }
    },
    "houses": {
      "system": "whole_sign",
      "ascendant": 158.31543091,
      "midheaven": 64.64823285,
      "cusps": [
        150,
        180
      ]
    },
    "aspects": [
      {
        "body1": "mercury",
        "body2": "uranus",
        "aspect": "trine",
        "angle": 120
      },
      {
        "body1": "moon",
        "body2": "venus",
        "aspect": "conjunction",
        "angle": 0
      }
    ],
    "warnings": []
  },
  "interpretation": null,
  "warnings": [],
  "credits_used": 1
}

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/positions' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: planetary-positions-api-example-001' \
+  --data '{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  }
}'

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

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • A custom zodiac-position interface
  • Numerical inputs for your own interpretation system
  • Motion and retrograde indicators in a calendar product

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 is a geocentric astrological position service, not an observing ephemeris with topocentric visibility or rise/set for every body.
  • It uses the same known-time requirements and 1900–2100 bounds as the natal chart engine.
  • A date with unknown time is not silently evaluated as an exact timed position.

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.

How is this different from the natal endpoint?

The current v1 numerical calculation is shared, but positions costs 1 credit and returns interpretation: null. Natal includes the localized rule-based reading and costs 5 credits.

Does it include retrograde status?

Yes. Each calculated planet includes motion fields. Longitude speed is estimated with a documented finite difference rather than inferred from zodiac signs.

Are these sidereal positions?

No. Western positions are tropical. Use the Vedic chart endpoint for the documented Lahiri sidereal profile.

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