Skip to content

Planetary Positions API

Ephemeris calculator for all planets

POST/astrology/planetsPOST/astrology/planets/monthlyPOST/astrology/aspectsPOST/astrology/aspects/monthlyPOST/astrology/houses

Calculate accurate tropical zodiac positions for all 14 celestial bodies for any date, time, and location. The bodies are the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith. Returns longitude, latitude, zodiac sign, degree within sign, daily motion speed, and retrograde status. Perfect for transit tracking, ephemeris tables, astrology apps, and planetary position widgets. Verified against NASA JPL Horizons.

Location first, chart second

The Planetary Positions API needs latitude, longitude, and timezone. Never ask users to type coordinates. Resolve a city with the Location endpoint first, then feed the result into the request. Timezone accepts a decimal offset or an IANA name.

1 Resolve the location

GET
curl "https://roxyapi.com/api/v2/location/search?q=New York" \
  -H "X-API-Key: YOUR_KEY"
# -> cities[0]: { latitude, longitude, timezone: "America/New_York" }

2 Call the Planetary Positions endpoint

POST /astrology/planets
# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/planets

Request

POST /api/v2/astrology/planets

Parameters

ParameterTypeDescription
langquerystring enumResponse language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default en.

Request body

FieldTypeDescription
date*string (date)Target date for planetary positions in YYYY-MM-DD format. Use current date for transit positions, or any historical/future date for research. Planets move daily, so this date determines their zodiac positions.
time*string (time)Time in 24-hour HH:MM:SS format for precise calculations. Moon moves ~13° per day, so time matters for accurate lunar position. Use 12:00:00 (noon) as default if exact time not needed.
nodeTypestring enumLunar node convention. "mean" is the smoothed average node, which always moves retrograde; "true" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass "mean" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to "true".
latitude*numberObserver latitude in decimal degrees (-90 to 90). While planetary longitudes are geocentric (same worldwide), this is needed for house calculations if extending functionality. For basic ephemeris, use 0 as default.
longitude*numberObserver longitude in decimal degrees (-180 to 180). Used for precise local time conversion. For basic planetary positions, this has minimal impact but ensures accuracy.
timezone*number or stringDecimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST, 5.75 for NPT) OR IANA name (e.g. "America/New_York"). IANA resolved to the DST-correct offset for the chart date.

Example request

POST /api/v2/astrology/planets
{
  "date": "2025-12-18",
  "time": "12:00:00",
  "nodeType": "true",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Response

Structured JSON with documented fields, covered by 13,405 automated tests per deploy, 3,620 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.

200 OK
{
  "planets": [
    {
      "name": "Sun",
      "longitude": 267.0272497797043,
      "latitude": -0.0001314154650795168,
      "sign": "Sagittarius",
      "degree": 27.027249779704277,
      "speed": 1.0182333534082488,
      "isRetrograde": false,
      "symbol": "☉",
      "tagline": "Self-awareness and ego",
      "description": "The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart, shaping how you assert yourself and pursue your goals.",
      "keywords": [
        "active",
        "awareness",
        "bright",
        "confidence",
        "consciousness",
        "creativity",
        "energy",
        "expression",
        "fire",
        "initiative"
      ],
      "interpretation": {
        "summary": "Sun in Sagittarius (Archer) brings adventurous, optimistic, independent energy to the themes of self-awareness and ego. This placement gives your Sun expression a distinctly Sagittarius character, shaping how you navigate these areas of life.",
        "planetMeaning": "The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart, shaping how you assert yourself and pursue your goals.",
        "signExpression": "Independent and strong-willed, Sagittarius personalities are all about going off the beaten path. Sagittarius isn't afraid to step away from the pack, and is a natural born leader who goes after what he or she wants, regardless of what other people think. Sagittarius is a born adventurer, and loves solo travel and exploration. Sagittarius also loves exploring the inner workings of their minds, and love stretching their horizons through a good book or movie.",
        "keywords": [
          "active",
          "awareness",
          "bright",
          "confidence",
          "consciousness",
          "adventurous",
          "optimistic",
          "independent"
        ]
      }
    },
    {
      "name": "Moon",
      "longitude": 252.07168441877383,
      "latitude": -4.999234688854935,
      "sign": "Sagittarius",
      "degree": 12.071684418773827,
      "speed": 11.932831010500621,
      "isRetrograde": false,
      "symbol": "☽",
      "tagline": "Inner emotional life",
      "description": "The Moon governs your emotional inner world, instincts, and subconscious patterns. It shapes how you nurture, seek comfort, and respond to stress. Your Moon sign reveals your deepest emotional needs and the way you process feelings.",
      "keywords": [
        "caretaker",
        "comfort",
        "emotion",
        "feeling",
        "femininity",
        "habits",
        "home",
        "intuition",
        "maturity",
        "motherhood"
      ],
      "interpretation": {
        "summary": "Moon in Sagittarius (Archer) brings adventurous, optimistic, independent energy to the themes of inner emotional life. This placement gives your Moon expression a distinctly Sagittarius character, shaping how you navigate these areas of life.",
        "planetMeaning": "The Moon governs your emotional inner world, instincts, and subconscious patterns. It shapes how you nurture, seek comfort, and respond to stress. Your Moon sign reveals your deepest emotional needs and the way you process feelings.",
        "signExpression": "Independent and strong-willed, Sagittarius personalities are all about going off the beaten path. Sagittarius isn't afraid to step away from the pack, and is a natural born leader who goes after what he or she wants, regardless of what other people think. Sagittarius is a born adventurer, and loves solo travel and exploration. Sagittarius also loves exploring the inner workings of their minds, and love stretching their horizons through a good book or movie.",
        "keywords": [
          "caretaker",
          "comfort",
          "emotion",
          "feeling",
          "femininity",
          "adventurous",
          "optimistic",
          "independent"
        ]
      }
    },
    {
      "name": "Mercury",
      "longitude": 249.01705022921158,
      "latitude": 1.063824690490812,
      "sign": "Sagittarius",
      "degree": 9.017050229211577,
      "speed": 1.408023063848276,
      "isRetrograde": false,
      "symbol": "☿",
      "tagline": "Communication",
      "description": "Mercury governs communication, intellect, and the way you process and exchange information. It rules logic, reason, and problem-solving, shaping how you learn, speak, write, and think. Mercury retrograde periods are known for disrupting communication, travel, and technology.",
      "keywords": [
        "analysis",
        "childhood",
        "communication",
        "curiosity",
        "education",
        "hands",
        "hobbies",
        "humor",
        "information",
        "intellect"
      ],
      "interpretation": {
        "summary": "Mercury in Sagittarius (Archer) brings adventurous, optimistic, independent energy to the themes of communication. This placement gives your Mercury expression a distinctly Sagittarius character, shaping how you navigate these areas of life.",
        "planetMeaning": "Mercury governs communication, intellect, and the way you process and exchange information. It rules logic, reason, and problem-solving, shaping how you learn, speak, write, and think. Mercury retrograde periods are known for disrupting communication, travel, and technology.",
        "signExpression": "Independent and strong-willed, Sagittarius personalities are all about going off the beaten path. Sagittarius isn't afraid to step away from the pack, and is a natural born leader who goes after what he or she wants, regardless of what other people think. Sagittarius is a born adventurer, and loves solo travel and exploration. Sagittarius also loves exploring the inner workings of their minds, and love stretching their horizons through a good book or movie.",
        "keywords": [
          "analysis",
          "childhood",
          "communication",
          "curiosity",
          "education",
          "adventurous",
          "optimistic",
          "independent"
        ]
      }
    },
    {
      "name": "Venus",
      "longitude": 262.4767460506304,
      "latitude": 0.015211951059664575,
      "sign": "Sagittarius",
      "degree": 22.476746050630425,
      "speed": 1.2588286082950901,
      "isRetrograde": false,
      "symbol": "♀",
      "tagline": "Love, beauty, and money",
      "description": "Venus governs love, beauty, pleasure, and values. It shapes how you experience romance, what you find attractive, and your relationship style. Venus also rules finances, aesthetics, and the things that bring you sensual joy.",
      "keywords": [
        "attractiveness",
        "beauty",
        "culture",
        "eros",
        "fantasy",
        "fashion",
        "finances",
        "flirting",
        "friendship",
        "glamour"
      ],
      "interpretation": {
        "summary": "Venus in Sagittarius (Archer) brings adventurous, optimistic, independent energy to the themes of love, beauty, and money. This placement gives your Venus expression a distinctly Sagittarius character, shaping how you navigate these areas of life.",
        "planetMeaning": "Venus governs love, beauty, pleasure, and values. It shapes how you experience romance, what you find attractive, and your relationship style. Venus also rules finances, aesthetics, and the things that bring you sensual joy.",
        "signExpression": "Independent and strong-willed, Sagittarius personalities are all about going off the beaten path. Sagittarius isn't afraid to step away from the pack, and is a natural born leader who goes after what he or she wants, regardless of what other people think. Sagittarius is a born adventurer, and loves solo travel and exploration. Sagittarius also loves exploring the inner workings of their minds, and love stretching their horizons through a good book or movie.",
        "keywords": [
          "attractiveness",
          "beauty",
          "culture",
          "eros",
          "fantasy",
          "adventurous",
          "optimistic",
          "independent"
        ]
      }
    },
    {
      "name": "Mars",
      "longitude": 272.5633560701814,
      "latitude": -0.8014721280427904,
      "sign": "Capricorn",
      "degree": 2.563356070181385,
      "speed": 0.7568358701417424,
      "isRetrograde": false,
      "symbol": "♂",
      "tagline": "Assertiveness and aggression",
      "description": "Mars governs action, desire, aggression, and physical energy. It shapes how you assert yourself, pursue goals, and handle conflict. Mars rules courage, competition, and sexuality, determining your drive and fighting spirit.",
      "keywords": [
        "action",
        "adventurous",
        "athletic",
        "brave",
        "courage",
        "desire",
        "dynamic",
        "energy",
        "excitement",
        "fiery"
      ],
      "interpretation": {
        "summary": "Mars in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of assertiveness and aggression. This placement gives your Mars expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
        "planetMeaning": "Mars governs action, desire, aggression, and physical energy. It shapes how you assert yourself, pursue goals, and handle conflict. Mars rules courage, competition, and sexuality, determining your drive and fighting spirit.",
        "signExpression": "Capricorn, the tenth sign in the zodiac, belongs to those born between the dates of December 22nd and January 19th. Smart, hardworking, and fully in control of their destiny, Capricorn signs will always get what they set their mind to, in both personal and professional life. No excuses. Capricorns may get a reputation as stubborn, but they simply know what they want, and also know how they wish other people would behave.",
        "keywords": [
          "action",
          "adventurous",
          "athletic",
          "brave",
          "courage",
          "ambitious",
          "disciplined",
          "patient"
        ]
      }
    },
    {
      "name": "Jupiter",
      "longitude": 112.97585754623071,
      "latitude": 0.2054485711759014,
      "sign": "Cancer",
      "degree": 22.975857546230714,
      "speed": -0.11017385105523658,
      "isRetrograde": true,
      "symbol": "♃",
      "tagline": "Luck and opportunity",
      "description": "Jupiter governs expansion, luck, wisdom, and higher learning. It shapes your belief systems, sense of optimism, and relationship with abundance. Jupiter transits bring periods of growth and opportunity, visiting each sign for approximately one year.",
      "keywords": [
        "abundance",
        "college",
        "culture",
        "curiosity",
        "diversity",
        "enlightenment",
        "expansion",
        "fortune",
        "generosity",
        "growth"
      ],
      "interpretation": {
        "summary": "Jupiter in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of luck and opportunity. This placement gives your Jupiter expression a distinctly Cancer character, shaping how you navigate these areas of life.",
        "planetMeaning": "Jupiter governs expansion, luck, wisdom, and higher learning. It shapes your belief systems, sense of optimism, and relationship with abundance. Jupiter transits bring periods of growth and opportunity, visiting each sign for approximately one year.",
        "signExpression": "Cancer, the fourth sign in the zodiac, belongs to those born between the dates of June 21st and July 22nd. Emotional, intuitive, and practically psychic; ruled by the moon and characterized by the crab, Cancer has so much going on in its watery depths. Cancer signs may seem prickly and standoffish at first meeting, once they make the decision to become friends with someone, that person has a friend for life.",
        "keywords": [
          "abundance",
          "college",
          "culture",
          "curiosity",
          "diversity",
          "intuitive",
          "nurturing",
          "protective"
        ]
      }
    },
    {
      "name": "Saturn",
      "longitude": 355.53482953192844,
      "latitude": -2.304273043381065,
      "sign": "Pisces",
      "degree": 25.534829531928438,
      "speed": 0.03648246609685657,
      "isRetrograde": false,
      "symbol": "♄",
      "tagline": "Responsibility, time, and routine",
      "description": "Saturn governs discipline, responsibility, structure, and karmic lessons. It defines your boundaries, ambitions, and relationship with authority. The Saturn return (approximately every 29 years) marks major life transitions and periods of maturation.",
      "keywords": [
        "ambition",
        "boundaries",
        "determination",
        "discipline",
        "experience",
        "focus",
        "karma",
        "leadership",
        "mastery",
        "mentorship"
      ],
      "interpretation": {
        "summary": "Saturn in Pisces (Fish) brings creative, sensitive, artistic energy to the themes of responsibility, time, and routine. This placement gives your Saturn expression a distinctly Pisces character, shaping how you navigate these areas of life.",
        "planetMeaning": "Saturn governs discipline, responsibility, structure, and karmic lessons. It defines your boundaries, ambitions, and relationship with authority. The Saturn return (approximately every 29 years) marks major life transitions and periods of maturation.",
        "signExpression": "Pisces, the twelfth sign in the zodiac, belongs to those between the dates of February 19th and March 20th. Smart, creative, and deeply intuitive, Pisces can be close to psychic. Pisces feel things deeply, and have incredibly strong gut reactions. A Pisces \"knows\" things from deep within, and can often judge whether a person or situation is good or bad. That doesn't mean a Pisces ignores the logical part of their brain, though. Deeply intelligent, Pisces have a profound respect for the power of the human mind. Is it a surprise that Albert Einstein was a Pisces?",
        "keywords": [
          "ambition",
          "boundaries",
          "determination",
          "discipline",
          "experience",
          "creative",
          "sensitive",
          "artistic"
        ]
      }
    },
    {
      "name": "Uranus",
      "longitude": 58.36843990942865,
      "latitude": -0.20110571795269302,
      "sign": "Taurus",
      "degree": 28.368439909428652,
      "speed": -0.035166368847029617,
      "isRetrograde": true,
      "symbol": "♅",
      "tagline": "Individuality and revolution",
      "description": "Uranus governs revolution, innovation, sudden change, and individuality. It disrupts outdated structures and catalyzes breakthrough moments. With an 84-year orbit, Uranus shapes generational attitudes toward freedom, technology, and social progress.",
      "keywords": [
        "avant-garde",
        "change",
        "comic",
        "determined",
        "experimental",
        "freedom",
        "game-changer",
        "genius",
        "global",
        "honesty"
      ],
      "interpretation": {
        "summary": "Uranus in Taurus (Bull) brings dependable, musical, practical energy to the themes of individuality and revolution. This placement gives your Uranus expression a distinctly Taurus character, shaping how you navigate these areas of life.",
        "planetMeaning": "Uranus governs revolution, innovation, sudden change, and individuality. It disrupts outdated structures and catalyzes breakthrough moments. With an 84-year orbit, Uranus shapes generational attitudes toward freedom, technology, and social progress.",
        "signExpression": "Taurus, the second sign in the zodiac, belongs to those born between the dates of April 20th and May 20th. Smart, ambitious, and trustworthy, Taurus is the anchor of the Zodiac. Amazing friends, colleagues, and partners, Taureans value honesty above all else and are proud that their personal relationships tend to be drama free. Bulls get the reputation of being stubborn, but they're not always stuck in their ways. This searching sign is willing to see another point of view, but they won't flip-flop on an opinion just to make someone else happy. They will shift their thinking only if they truly have a change of heart.",
        "keywords": [
          "avant-garde",
          "change",
          "comic",
          "determined",
          "experimental",
          "dependable",
          "musical",
          "practical"
        ]
      }
    },
    {
      "name": "Neptune",
      "longitude": 359.3921810708607,
      "latitude": -1.3410693024111664,
      "sign": "Pisces",
      "degree": 29.392181070860715,
      "speed": 0.0048051280757590575,
      "isRetrograde": false,
      "symbol": "♆",
      "tagline": "Dreams, healing, and intuition",
      "description": "Neptune governs dreams, intuition, illusion, and the subconscious mind. It dissolves boundaries between reality and imagination, ruling spirituality, creativity, and psychic sensitivity. Neptune changes signs roughly once per generation, shaping collective ideals and fantasies.",
      "keywords": [
        "artistic",
        "calm",
        "compassionate",
        "deep",
        "dreams",
        "ecstacy",
        "empathic",
        "enlightenment",
        "fantasy",
        "flexible"
      ],
      "interpretation": {
        "summary": "Neptune in Pisces (Fish) brings creative, sensitive, artistic energy to the themes of dreams, healing, and intuition. This placement gives your Neptune expression a distinctly Pisces character, shaping how you navigate these areas of life.",
        "planetMeaning": "Neptune governs dreams, intuition, illusion, and the subconscious mind. It dissolves boundaries between reality and imagination, ruling spirituality, creativity, and psychic sensitivity. Neptune changes signs roughly once per generation, shaping collective ideals and fantasies.",
        "signExpression": "Pisces, the twelfth sign in the zodiac, belongs to those between the dates of February 19th and March 20th. Smart, creative, and deeply intuitive, Pisces can be close to psychic. Pisces feel things deeply, and have incredibly strong gut reactions. A Pisces \"knows\" things from deep within, and can often judge whether a person or situation is good or bad. That doesn't mean a Pisces ignores the logical part of their brain, though. Deeply intelligent, Pisces have a profound respect for the power of the human mind. Is it a surprise that Albert Einstein was a Pisces?",
        "keywords": [
          "artistic",
          "calm",
          "compassionate",
          "deep",
          "dreams",
          "creative",
          "sensitive",
          "artistic"
        ]
      }
    },
    {
      "name": "Pluto",
      "longitude": 302.3363678332005,
      "latitude": -3.7643747383268287,
      "sign": "Aquarius",
      "degree": 2.336367833200484,
      "speed": 0.027215907045103904,
      "isRetrograde": false,
      "symbol": "♇",
      "tagline": "Sex, death, and transformation",
      "description": "Pluto governs transformation, power, death and rebirth, and the unconscious mind. It reveals where you must confront your deepest fears to achieve self-mastery. With a 248-year orbit, Pluto shapes generational attitudes toward power, control, and radical change.",
      "keywords": [
        "alchemy",
        "bold",
        "charismatic",
        "complex",
        "courageous",
        "empowered",
        "evolution",
        "independent",
        "intense",
        "loyal"
      ],
      "interpretation": {
        "summary": "Pluto in Aquarius (Water Bearer) brings imaginative, idealistic, intuitive energy to the themes of sex, death, and transformation. This placement gives your Pluto expression a distinctly Aquarius character, shaping how you navigate these areas of life.",
        "planetMeaning": "Pluto governs transformation, power, death and rebirth, and the unconscious mind. It reveals where you must confront your deepest fears to achieve self-mastery. With a 248-year orbit, Pluto shapes generational attitudes toward power, control, and radical change.",
        "signExpression": "Aquarius, the eleventh sign in the zodiac, belongs to those born between the dates of January 20th to February 18th. Independent and enigmatical, Aquarians are unique. There is no one quite like an Aquarius, and because each is so incredibly individual, it can be tough to describe them as a group. Aquarians don't like labels, and may shy away from any adjective, even the good ones you might bestow upon them. Aquarians believe in the nature of change and evolution, and even though they're a fixed sign, they may not necessarily believe they are the \"same\" people they were when they were born.",
        "keywords": [
          "alchemy",
          "bold",
          "charismatic",
          "complex",
          "courageous",
          "imaginative",
          "idealistic",
          "intuitive"
        ]
      }
    },
    {
      "name": "North Node",
      "longitude": 342.2666346201235,
      "latitude": 0,
      "sign": "Pisces",
      "degree": 12.266634620123511,
      "speed": -0.23737007694458612,
      "isRetrograde": true,
      "symbol": "☊",
      "tagline": "Life purpose and destiny",
      "description": "The North Node represents your soul's growth direction and life purpose. It points to unfamiliar qualities and experiences you are meant to develop. Leaning into the North Node path brings deep fulfillment despite its inherent discomfort.",
      "keywords": [
        "destiny",
        "life purpose",
        "soul growth",
        "future direction",
        "karmic reward",
        "evolution",
        "new experiences",
        "growth edge",
        "aspiration",
        "calling"
      ],
      "interpretation": {
        "summary": "North Node in Pisces (Fish) brings creative, sensitive, artistic energy to the themes of life purpose and destiny. This placement gives your North Node expression a distinctly Pisces character, shaping how you navigate these areas of life.",
        "planetMeaning": "The North Node represents your soul's growth direction and life purpose. It points to unfamiliar qualities and experiences you are meant to develop. Leaning into the North Node path brings deep fulfillment despite its inherent discomfort.",
        "signExpression": "Pisces, the twelfth sign in the zodiac, belongs to those between the dates of February 19th and March 20th. Smart, creative, and deeply intuitive, Pisces can be close to psychic. Pisces feel things deeply, and have incredibly strong gut reactions. A Pisces \"knows\" things from deep within, and can often judge whether a person or situation is good or bad. That doesn't mean a Pisces ignores the logical part of their brain, though. Deeply intelligent, Pisces have a profound respect for the power of the human mind. Is it a surprise that Albert Einstein was a Pisces?",
        "keywords": [
          "destiny",
          "life purpose",
          "soul growth",
          "future direction",
          "karmic reward",
          "creative",
          "sensitive",
          "artistic"
        ]
      }
    },
    {
      "name": "South Node",
      "longitude": 162.26663462012357,
      "latitude": 0,
      "sign": "Virgo",
      "degree": 12.266634620123568,
      "speed": -0.23737007694458612,
      "isRetrograde": true,
      "symbol": "☋",
      "tagline": "Past life gifts and comfort zone",
      "description": "The South Node represents your karmic past, innate talents, and comfort zone. These are patterns you have already mastered, possibly from past lives. The key is to use these gifts as a foundation while stretching toward North Node growth.",
      "keywords": [
        "innate talents",
        "past life wisdom",
        "natural abilities",
        "comfort zone",
        "mastered skills",
        "karmic gifts",
        "familiarity",
        "instinctive knowledge"
      ],
      "interpretation": {
        "summary": "South Node in Virgo (Virgin) brings graceful, organized, kind energy to the themes of past life gifts and comfort zone. This placement gives your South Node expression a distinctly Virgo character, shaping how you navigate these areas of life.",
        "planetMeaning": "The South Node represents your karmic past, innate talents, and comfort zone. These are patterns you have already mastered, possibly from past lives. The key is to use these gifts as a foundation while stretching toward North Node growth.",
        "signExpression": "Virgo, the sixth sign of the zodiac, belongs to those born between the dates of August 23rd and September 22nd. Smart, sophisticated, and kind, Virgo gets the job done without complaining. Virgos are amazing friends, always there to lend a hand and also lend advice. Practical Virgos are incredibly adept at big picture thinking, and planning out their life, their vacations, and what they're going to do today isn't a drag it makes them feel in control and secure.",
        "keywords": [
          "innate talents",
          "past life wisdom",
          "natural abilities",
          "comfort zone",
          "mastered skills",
          "graceful",
          "organized",
          "kind"
        ]
      }
    },
    {
      "name": "Chiron",
      "longitude": 22.703657895474453,
      "latitude": 0.5243197063570323,
      "sign": "Aries",
      "degree": 22.703657895474453,
      "speed": -0.013912565183417769,
      "isRetrograde": true,
      "symbol": "⚷",
      "tagline": "Healing and inner wounds",
      "description": "Chiron, the Wounded Healer, represents your deepest vulnerability and your greatest capacity to heal others. Through confronting this core wound, you develop profound empathy and mentorship ability.",
      "keywords": [
        "healing",
        "wisdom",
        "mentorship",
        "teaching",
        "empathy",
        "compassion",
        "holistic",
        "integration",
        "bridge-builder",
        "acceptance"
      ],
      "interpretation": {
        "summary": "Chiron in Aries (Ram) brings ambitious, independent, impatient energy to the themes of healing and inner wounds. This placement gives your Chiron expression a distinctly Aries character, shaping how you navigate these areas of life.",
        "planetMeaning": "Chiron, the Wounded Healer, represents your deepest vulnerability and your greatest capacity to heal others. Through confronting this core wound, you develop profound empathy and mentorship ability.",
        "signExpression": "Aries, the first sign in the zodiac, belongs to those born between the dates of March 21st and April 19th. Aries are the trailblazers. Passionate and independent, Aries will never do something just because everyone else is doing it. A Ram needs to be 100 percent committed to the task at hand. Competitive to the max, the best way to motivate an Aries is to turn something into a contest. Aries will put everything they have (and then some) into winning. Loyal, smart, and impulsive, they always have multiple projects on their mind, and won't be satisfied until their work, social life, and personal lives line up exactly with the dream life they've envisioned. Those who are drawn to magnetic Aries may have trouble keeping up, but if they can, they'll have a friend for life.",
        "keywords": [
          "healing",
          "wisdom",
          "mentorship",
          "teaching",
          "empathy",
          "ambitious",
          "independent",
          "impatient"
        ]
      }
    },
    {
      "name": "Black Moon Lilith",
      "longitude": 239.76575917528004,
      "latitude": -5.011623401841819,
      "sign": "Scorpio",
      "degree": 29.76575917528004,
      "speed": 0.11203615542095235,
      "isRetrograde": false,
      "symbol": "⚸",
      "tagline": "Primal instinct and the reclaimed self",
      "description": "Black Moon Lilith marks where you meet your primal, unfiltered self. It points to the instincts you were taught to suppress, and the life area where reclaiming them restores your power and authenticity.",
      "keywords": [
        "authenticity",
        "autonomy",
        "instinct",
        "raw power",
        "self-possession",
        "liberation",
        "honesty",
        "magnetism",
        "boundaries",
        "reclamation"
      ],
      "interpretation": {
        "summary": "Black Moon Lilith in Scorpio (Scorpion) brings seductive, passionate, independent energy to the themes of primal instinct and the reclaimed self. This placement gives your Black Moon Lilith expression a distinctly Scorpio character, shaping how you navigate these areas of life.",
        "planetMeaning": "Black Moon Lilith marks where you meet your primal, unfiltered self. It points to the instincts you were taught to suppress, and the life area where reclaiming them restores your power and authenticity.",
        "signExpression": "Scorpio, the eighth sign in the zodiac, belongs to those born between the dates of October 23rd and November 21st. Passionate, independent, and unafraid to blaze their own trail no matter what others think, Scorpio signs make a statement wherever they go. They love debates, aren't afraid of controversy, and won't back down from a debate. They also hate people who aren't genuine, and are all about being authentic, even if authentic isn't pretty.",
        "keywords": [
          "authenticity",
          "autonomy",
          "instinct",
          "raw power",
          "self-possession",
          "seductive",
          "passionate",
          "independent"
        ]
      }
    }
  ]
}

Response fields

FieldTypeDescription
planets*array of objectAll 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, speeds, retrograde status, meanings, and interpretations.
planets[].name*stringPlanet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). The lunar nodes follow the request nodeType, which defaults to the true (osculating) node; pass "mean" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected.
planets[].longitude*numberApparent geocentric tropical longitude on the true ecliptic of date, in degrees (0-360): light time and aberration applied, nutation included, the convention desktop chart software and the NASA JPL Horizons observer tables print, so it compares directly with either.
planets[].latitude*numberApparent geocentric ecliptic latitude of date, in degrees.
planets[].sign*stringTropical zodiac sign this planet occupies.
planets[].degree*numberDegree within the zodiac sign (0-29.999).
planets[].speed*numberDaily motion in degrees per day. Negative values indicate retrograde.
planets[].isRetrograde*booleanWhether the planet is in apparent retrograde motion.
planets[].symbolstringUnicode astronomical symbol for this planet.
planets[].taglinestringShort tagline summarizing what this planet governs.
planets[].descriptionstringBrief description of this planet in astrological context.
planets[].keywordsarray of stringKey themes and traits associated with this planet.
planets[].interpretationobjectPlanet-in-sign interpretation. How this planet expresses through the zodiac sign it currently occupies.
planets[].interpretation.summary*stringInterpretation of this planet in its current zodiac sign.
Show all fields
FieldTypeDescription
planets[].interpretation.planetMeaning*stringGeneral meaning of this planet in astrology.
planets[].interpretation.signExpression*stringHow this planet expresses through the current sign.
planets[].interpretation.keywords*array of stringKeywords for this specific planet-in-sign combination.

Supported options

lang

entrdeeshiptfrruzh-Hanszh-Hant

nodeType

meantrue

Call it in your language.

Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.

TypeScript
import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.astrology.getPlanetaryPositions({ body: { date: '2025-12-18', time: '12:00:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' } })

Install: npm install @roxyapi/sdk

Prefer to try before you write code? Run this Western Astrology endpoint live in the API playground and inspect a real production response.

More Planetary Positions endpoints

The Planetary Positions API bundles these related endpoints under one key.

POST/astrology/planets/monthly

Monthly Ephemeris - Daily tropical planetary positions for a month

Get daily tropical ecliptic positions for all 14 Western bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for an entire month. Returns longitude, zodiac sign, degree within sign, and retrograde status for each body on each day, calculated at noon UTC. Omit year and month to get the month in progress, so a published ephemeris page stays current without a redeploy. Essential for ephemeris tables, transit tracking, retrograde calendars, and planetary movement charts. Monthly ephemeris API, tropical position table, daily planet transit positions, ecliptic longitude calculator. Verified against NASA JPL Horizons.

Try it live
POST/astrology/aspects

Calculate planetary aspects - Aspect finder for any date and time

Calculate all major and minor aspects between planets for any date and time. Finds conjunctions (0°), oppositions (180°), trines (120°), squares (90°), sextiles (60°), and minor aspects. Returns aspect type, exact angle, orb, applying/separating status, and strength (0-100). Filter by specific planets or aspect types. Perfect for aspect tables, transit analysis, and aspect pattern detection. Uses standard Western astrology orbs.

Try it live
POST/astrology/aspects/monthly

Monthly Aspects - Tropical aspect calendar for an entire month

Get every planetary aspect that perfects during a given month, across the 13 non-lunar Western bodies: the Sun and Mercury through Pluto, both lunar nodes, Chiron and Black Moon Lilith. Detects nine aspects, five major (conjunction, sextile, square, trine, opposition) and four minor (semi-sextile, semi-square, sesquiquadrate, quincunx), each with its own traditional orb, and returns the exact date and time of closest approach in your timezone along with the nature of the aspect. Calculated on tropical longitudes. The Moon is excluded because it forms hundreds of aspects a month and belongs in a daily view rather than a monthly one. Omit year and month to get the month in progress, so a published calendar stays current without a redeploy. Essential for monthly forecast copy, transit calendars, electional timing, and newsletter automation. Monthly aspect calendar API, exact aspect times, planetary aspect ephemeris, transit timing. Verified against NASA JPL Horizons.

Try it live
POST/astrology/houses

Calculate house cusps - House system calculator with comparison

Calculate astrological house cusps using Placidus, Whole Sign, Equal, or Koch house systems. Returns all 12 house cusps with zodiac signs, degrees, Ascendant, and Midheaven. Use "all" parameter to compare all 4 house systems side-by-side. Perfect for astrology charts, house cusp tables, and educational tools showing house system differences. Includes accurate Ascendant and MC calculations.

Try it live

Remote MCP for AI agents

Every Western Astrology endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.

Claude Code / Cursor
claude mcp add --transport http \
  roxy-astrology https://roxyapi.com/mcp/astrology \
  --header "X-API-Key: YOUR_KEY"

Tool name for POST /astrology/planets: post_astrology_planets. Full MCP setup guide

What you can build

Launch natal chart apps with professional-grade accuracy: birth charts, planet positions, house placements, aspects, and element analysis ready for your UI

Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics

Ship personalized horoscope platforms: editorial daily, weekly, monthly, and yearly columns with unique content per sign, the dated events each one rests on returned beside the prose for fact-checking, active transit metadata, Moon phase data, and any past or future period on request for editorial pre-publishing

Build AI astrology chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers and calls every astrology endpoint with zero integration code

Power wellness and lifestyle apps with real-time transits, moon phase calendars, solar returns, and planetary movement alerts for self-discovery features

Create astrology content engines: automated zodiac content with house-based uniqueness per sign, horoscope newsletters with real lunar event dates, transit alerts, and year-ahead pages built from every eclipse and every retrograde and direct station of the year with the house each one falls in for that sign

Drop-in UI components and no-code widgets.

Render Planetary Positions API responses without building charts yourself. Install the npm package and drop these into Next.js, React, Vue, Svelte, Angular, or plain HTML, or embed the very same component on Squarespace, Wix, or WordPress by pasting one snippet, with no backend and no build step. They belong to one library that covers the entire spiritual stack rather than astrology alone, MIT licensed and included in every plan at no extra cost, never a separate product and never an upsell. The Planetary Positions API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.

MIT licensedFramework agnosticThemeable via CSS variablesnpm or CDN
Show all Planetary Positions UI components
ElementRenders
<roxy-aspects-table>Aspect rows coloured by nature with orb and strength, plus detected chart patterns
<roxy-ephemeris-table>Per-body sign changes and retrograde windows for the month, over the full daily position grid

Component preview

The real component, running on sample data.

Loading the component...

Related capabilities

Planetary Positions API FAQ

What does the Planetary Positions API return?

Calculate accurate tropical zodiac positions for all 14 celestial bodies for any date, time, and location. Every response is structured JSON with documented fields, not free text, so you map it straight into your product.

How do I authenticate with the Planetary Positions API?

Pass your key in the X-API-Key header on every request. Keys are delivered instantly at checkout with no approval queue. Use a secret sk key server side, or mint a publishable pk key locked to your origins for browser and no-code use.

Does the Planetary Positions API support multiple languages?

Yes. Append the lang query parameter to any endpoint for responses in English, German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The translated payload includes the full interpretation text, not just field labels.

Do I need coordinates to call the Planetary Positions API?

No. Call GET /location/search with a city name first, then pass latitude, longitude, and timezone from the first result into the request. Never ask users to type coordinates. Timezone accepts a decimal offset or an IANA name.

Is the Planetary Positions API available over Remote MCP for AI agents?

Yes. Every endpoint is exposed as a callable tool on the Remote MCP server at https://roxyapi.com/mcp/astrology over Streamable HTTP, so Claude, ChatGPT, Cursor, and any MCP client auto-discover it with no local setup or Docker.

How is the Planetary Positions API billed?

Flat pricing: 1 request equals 1 quota unit, REST and MCP identical, with no credit weighting or per-token markup. Every plan includes all 18 domains, so the Planetary Positions API is included at no extra cost.

What nodeType values does the Planetary Positions API accept?

The nodeType parameter accepts mean, true. Case-insensitive where it is a path value.

Start using Planetary Positions API today.

Birth charts checked cusp by cusp, and horoscopes that name the dated sky events behind each reading.

All 18 domains included with every plan. Every endpoint, MCP server, SDK, and templates.

Plans from $39/mo, starting at $1.80 per domain on annual billing. No credit card required for testing.

View Pricing & Get API Key