Zodiac Sign API: Birthdate to Full Profile in 5 Minutes

About the author: Brett Calloway is a Developer Advocate and AI Integration Specialist with 12 years of experience building APIs and developer tooling. He has led developer relations at two Series B SaaS companies and spoken at PyCon and JSConf on building context-rich AI agents using Model Context Protocol.

Every social app, dating platform, and user profile page wants the same thing: take a birthdate, return something personal. Zodiac signs are the fastest path to personalized content that users actually engage with. A zodiac sign API gives you structured astrology data from a single request, no domain knowledge required. The pattern is simple. Start with a zodiac badge. Layer on a birth chart. Add daily content. Then compatibility. Each step is one endpoint, and you never have to rebuild what you already shipped.

This tutorial walks through four endpoints that take you from a basic sign lookup to a full astrological profile. Every code example uses real request and response schemas from the RoxyAPI Astrology API. Copy, paste, run.

How to get a zodiac sign from any birthdate

The signs endpoint returns all 12 tropical zodiac signs with date ranges, elements, ruling planets, and personality descriptions. You match the birthdate against the date ranges client-side, or you can fetch a single sign by ID.

To get the full list of all 12 signs:

curl -H "X-API-Key: YOUR_KEY" \
  https://roxyapi.com/api/v2/astrology/signs

Each sign in the response includes id, name, symbol, element, dates (with start and end), and a description. That gives you everything needed for a zodiac badge, a sign selector dropdown, or a profile card.

For a detailed profile of a single sign:

curl -H "X-API-Key: YOUR_KEY" \
  https://roxyapi.com/api/v2/astrology/signs/aries

The single-sign response adds symbolName, modality, rulingPlanet, keywords, a full description object with short and long fields, plus strengths, motto, gifts, challenges, weapon, and a famous array of notable people born under that sign. That is enough structured data to populate an entire profile section without writing a single line of astrology copy.

Ready to build this? RoxyAPI Astrology API gives you 12 zodiac signs, natal charts, daily horoscopes, and compatibility scores under one subscription. See pricing.

How to generate a full natal chart with planet positions

Once you have birth time and location, you unlock the natal chart endpoint. This is the step where a simple zodiac badge becomes a serious astrology feature. Send a POST with five fields: date, time, latitude, longitude, and timezone.

curl -X POST https://roxyapi.com/api/v2/astrology/natal-chart \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": -5
  }'

The response returns planets (an array with name, sign, degree, house, isRetrograde, and a full interpretation object), houses (all 12 cusps with sign and degree), aspects (with type, orb, strength, and interpretation), ascendant, midheaven, and a summary with dominantElement, dominantModality, retrogradePlanets, plus element and modality distributions. You can optionally pass houseSystem as placidus, whole-sign, equal, or koch.

Each planet includes an interpretation object with summary, detailed, and keywords fields. That means you get both raw astronomical data (longitude, degree, house number) and content-ready narrative text in the same response. You can render a visual chart from the numbers or display the interpretation text directly, depending on your use case. The aspectsInterpretation field at the chart level tells you whether the overall pattern is harmonious, challenging, or balanced, along with counts for each type. Planet positions are verified against NASA JPL Horizons.

How to add daily horoscopes for all 12 zodiac signs

Daily content drives return visits. One GET request per sign gives you a fresh horoscope based on real planetary transits. The forecasts use whole-sign house positions, so each sign receives unique content, not generic templates rotated between signs.

curl -H "X-API-Key: YOUR_KEY" \
  https://roxyapi.com/api/v2/astrology/horoscope/aries/daily

The response includes sign, date, overview, love, career, health, finance, advice, luckyNumber, luckyColor, compatibleSigns, activeTransits, moonSign, moonPhase, and an energyRating from 1 to 10. The activeTransits field lists each planet, its current sign, and which house it activates for the queried sign.

Pass an optional date query parameter in YYYY-MM-DD format to schedule content in advance or fetch past horoscopes. Loop through all 12 signs to populate a full horoscope page. That is 12 GET requests, each returning structured JSON with six content sections plus metadata. Weekly and monthly endpoints follow the same pattern at /{sign}/weekly and /{sign}/monthly.

How to compare two users for relationship compatibility

Compatibility is the feature that makes users invite other users. The compatibility score endpoint takes two sets of birth details and returns a scored breakdown across five categories: romantic, emotional, intellectual, physical, and spiritual.

curl -X POST https://roxyapi.com/api/v2/astrology/compatibility-score \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person1": {
      "date": "1990-07-15",
      "time": "14:30:00",
      "latitude": 40.7128,
      "longitude": -74.006,
      "timezone": -5
    },
    "person2": {
      "date": "1992-03-20",
      "time": "09:15:00",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "timezone": -8
    }
  }'

The response includes overallScore (0 to 100), categories (each scored 0 to 100), persons (Sun, Moon, Venus, Mars positions for each person), signCompatibility (narrative analysis for Sun, Moon, Venus, Mars pairs), elementBalance, an archetype (one of eight labels like "Kindred Spirits" or "The Power Couple"), strengths, challenges, summary, interpretation, aspectBreakdown, and keyAspects with relationship-specific descriptions.

The categories object breaks the overall score into five dimensions. Romantic compatibility weighs Sun-Moon, Venus-Mars, and Sun-Venus cross-chart aspects. Emotional compatibility focuses on Moon-Moon and Moon-Venus. Intellectual compatibility uses Mercury-Mercury and Sun-Mercury. This level of detail lets you build nuanced matching UIs: show the overall score as a headline number, then expand into category breakdowns for users who want depth. That is a complete compatibility report from a single POST.

The progressive enhancement pattern for astrology features

This is the architecture pattern that matters. You do not need to plan your full astrology feature set on day one. Start with the signs endpoint for a zodiac badge on user profiles. That is one GET request and zero user friction, since you already have the birthdate.

When users engage, add the natal chart endpoint behind a "See your full chart" button. That requires birth time and location, which you collect incrementally. Layer on daily horoscopes for a content feed that refreshes every day. Add compatibility when you want social features. Each step is one new endpoint call against the same API key. No migration, no new dependency, no rebuild.

This progressive pattern keeps integration cost low at each stage. You ship the zodiac badge in an afternoon, measure engagement, and decide whether to invest in the full chart. The API schema stays consistent across all endpoints, so your data models grow but never break. Apps with personalized astrology features tend to see meaningfully higher daily active user rates, because the content is unique per user and changes over time.

What the zodiac sign API response looks like

Here is a trimmed example of what the single-sign endpoint returns for Aries. This is real structured data, not a paragraph of text you need to parse:

{
  "id": "aries",
  "name": "Aries",
  "symbol": "♈",
  "symbolName": "The Ram",
  "element": "Fire",
  "modality": "Cardinal",
  "rulingPlanet": "Mars",
  "dates": { "start": "Mar 21", "end": "Apr 19" },
  "keywords": ["ambitious", "courageous", "energetic"],
  "description": {
    "short": "...",
    "long": "..."
  },
  "strengths": ["..."],
  "motto": "I am.",
  "gifts": "...",
  "challenges": "...",
  "weapon": "...",
  "famous": ["Leonardo da Vinci", "Lady Gaga"]
}

Every field has a clear type. element is always one of Fire, Earth, Air, or Water. modality is Cardinal, Fixed, or Mutable. The keywords array gives you personality trait tags you can render as pills or badges. The famous array adds social proof. This is the kind of structured, typed response that saves you from maintaining your own astrology content database. Full schema documentation is in the API reference.

Frequently Asked Questions

Q: Do I need to know astrology to use the zodiac sign API? A: No. The API returns structured data with human-readable interpretations included. Each planet placement, aspect, and horoscope section comes with pre-written narrative text. You render JSON, not interpret celestial mechanics.

Q: How accurate are the planet positions in the natal chart endpoint? A: All planetary positions are calculated using the Roxy Ephemeris, verified against NASA JPL Horizons. The test suite includes 828 gold standard test cases cross-referenced against authoritative sources. Sub-arcminute precision for all major planets from Sun through Pluto.

Q: How often does the daily horoscope content refresh? A: Daily horoscopes are calculated from real-time planetary transits and update every day. Each sign receives unique content based on whole-sign house positions. You can also pass a date parameter to fetch future or past forecasts.

Q: Is there a free tier for testing the zodiac sign API? A: All plans include access to every endpoint across all nine API domains. Check current plan options and pricing at roxyapi.com/pricing. Every plan supports signs, natal charts, horoscopes, and compatibility scoring.

Q: Can I use the compatibility endpoint for friend matching, not just romantic matching? A: Yes. The compatibility score endpoint returns five category scores (romantic, emotional, intellectual, physical, spiritual). For friend matching, weight the emotional and intellectual scores higher. The structured response lets you build any matching logic on top.

Start with a zodiac badge, ship a full astrology suite

The zodiac sign API pattern is straightforward. One GET gives you a sign. One POST gives you a full chart. One GET per sign gives you daily content. One POST gives you compatibility. Four endpoints cover the entire astrology feature lifecycle from profile badge to relationship matching.

Every endpoint returns structured JSON with typed fields, pre-written interpretations, and consistent schemas. You start small and grow without rebuilding. The RoxyAPI Astrology API covers all four steps under a single API key and subscription. Check the full endpoint list in the API reference, or see pricing to get started.