Astro APIastro.com ↗
Access zodiac sign characteristics, real-time planetary positions, current astrological aspects, and weekly horoscopes from Astro.com via a structured JSON API.
What is the Astro API?
This API exposes 4 endpoints covering astrological data sourced from Astro.com, including real-time planetary positions with degree, sign, arc minutes, and declination for each celestial body. The get_sign_characteristics endpoint returns multi-paragraph personality descriptions, strengths, weaknesses, and compatibility notes for all 12 zodiac signs. The get_general_horoscope endpoint delivers the current weekly tendencies text as a structured array of content paragraphs.
curl -X GET 'https://api.parse.bot/scraper/c900e9ec-5bb2-4ac8-9ad8-c5d8eba88f2e/get_sign_characteristics?sign=Aries' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace astro-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Astro SDK — zodiac characteristics, planetary positions, and weekly horoscopes."""
from parse_apis.astro_astrology_api import Astro, ZodiacSign, SignNotFound
client = Astro()
# Fetch characteristics for a specific zodiac sign using the enum.
aries = client.signs.get(sign=ZodiacSign.ARIES)
print(aries.sign, aries.summary[:100])
for trait in aries.characteristics[:2]:
print(trait[:80])
# Get current planetary positions — a single snapshot of all celestial bodies.
snapshot = client.planetarysnapshots.current()
for planet in snapshot.planets[:3]:
print(planet.body, planet.sign, planet.degree, planet.minutes)
# Get the weekly horoscope text.
horoscope = client.horoscopes.weekly()
print(horoscope.title, horoscope.content[0][:120])
# Typed error handling: catch invalid sign input.
try:
client.signs.get(sign="InvalidSign")
except SignNotFound as exc:
print(f"Sign not found: {exc.sign}")
print("exercised: signs.get / planetarysnapshots.current / horoscopes.weekly / SignNotFound")
Get comprehensive zodiac sign characteristics including personality traits, strengths, weaknesses, and compatibility information. Returns a meta description summary plus multiple paragraphs of personality description from Liz Greene's characterizations on Astro.com.
| Param | Type | Description |
|---|---|---|
| signrequired | string | Zodiac sign name. Accepted values: Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn, Aquarius, Pisces. |
{
"type": "object",
"fields": {
"sign": "string - capitalized zodiac sign name",
"traits": "object - additional structured traits (may be empty)",
"summary": "string - brief meta description of the sign",
"characteristics": "array of strings - paragraphs describing personality traits"
},
"sample": {
"data": {
"sign": "Aries",
"traits": {},
"summary": "You need a cause, a mission, a battle in which you can trounce the enemy. The slightest whiff of a challenge and out comes that old suit of armour, kept clean and polished in case of emergency. Passionate conviction, courage, bravery, vision, a touch of fanaticism - all these things belong to the Aries soul.",
"characteristics": [
"You need a cause, a mission, a battle in which you can trounce the enemy.",
"Aries is a fire sign, and all fire signs tend to mythologise life and themselves."
]
},
"status": "success"
}
}About the Astro API
Zodiac Sign Characteristics
The get_sign_characteristics endpoint accepts a sign parameter (e.g., Aries, Taurus, Scorpio) and returns a characteristics array of descriptive paragraphs, a summary string pulled from the sign's meta description, and a traits object for any structured trait data available. This covers all 12 standard Western zodiac signs.
Planetary Positions and Aspects
get_planetary_positions requires no inputs and returns a planets array where each object includes body (the celestial body name), degree, sign, minutes (arc minutes), and declination. Data reflects current real-time positions. The get_aspects endpoint also takes no inputs and returns an aspects array alongside a message string summarizing active celestial events. Note that get_aspects may return an empty aspects array when no notable aspect data is available, with context provided only through the message field.
Weekly Horoscope
get_general_horoscope returns a title string and a content array of strings representing the weekly forecast paragraphs. Content is filtered to lines longer than 50 characters, so very short transitional lines are excluded from the response. This endpoint reflects the general (non-sign-specific) weekly tendencies published on Astro.com and updates on a weekly cycle.
Coverage Notes
All four endpoints cover publicly available astrological content. There are no input filters for date ranges or geographic coordinates — positions and horoscopes represent current or current-week values only.
The Astro API is a managed, monitored endpoint for astro.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when astro.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official astro.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display real-time planetary positions with degree and sign data in an astronomy or astrology dashboard
- Populate zodiac sign profile pages with multi-paragraph personality traits and compatibility notes from
get_sign_characteristics - Deliver a weekly horoscope digest to app users using the
contentarray fromget_general_horoscope - Build a daily celestial event summary widget using the
messagefield fromget_aspects - Generate zodiac-based matchmaking features using the
traitsandcharacteristicsfields - Provide sign-specific onboarding copy in wellness or journaling apps by querying individual zodiac signs
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Astro.com provide an official developer API?+
What does `get_planetary_positions` actually return for each celestial body?+
planets array includes five fields: body (the name of the celestial body), degree (position in degrees within its sign), sign (the zodiac sign it occupies), minutes (arc minutes for precision), and declination. The endpoint takes no inputs and always reflects current positions.Can I retrieve horoscopes for a specific zodiac sign rather than the general weekly forecast?+
get_general_horoscope, which is not sign-specific. Sign-specific forecasts are not included. You can fork this API on Parse and revise it to add a sign-specific horoscope endpoint.Is historical planetary position data available, or can I query positions for a specific date?+
get_planetary_positions returns current real-time data only — there is no date parameter for historical or future ephemeris queries. You can fork this API on Parse and revise it to add a date-based planetary position endpoint.What happens when `get_aspects` returns an empty aspects array?+
aspects array will be empty and the message string carries the summary of current celestial events. Applications should handle the empty-array case and fall back to rendering the message field.