canonical: https://jentic.com/apis/natalchart.ai/natalchart # NatalChart.AI API The NatalChart.AI API computes astrology charts from birth data using the Swiss Ephemeris and returns the results as JSON, with tropical zodiac, Placidus houses, and the five major aspects. Beyond the natal chart it calculates transits over a window of up to 92 days, synastry between two people, solar return charts, day-by-day timing scores for an activity, and relocation scores that rank major cities for one chart. Responses contain calculated positions and scores only, with no generated text and no AI calls, and the spec states that request bodies are never stored. ## For AI agents Calculate natal charts, transits, synastry, solar returns, activity timing, and relocation scores from a birth date, time, and coordinates, returned as structured JSON. ## Scope Does not write horoscope interpretations, geocode place names, or calculate sidereal or Vedic charts. Use for Swiss Ephemeris tropical chart calculations only. ## Capabilities - Compute a full natal chart from a birth date, local time, latitude, and longitude: every body's longitude, sign, house, speed, and retrograde flag plus angles and Placidus cusps - Return individual chart slices such as planets, angles, house cusps, major aspects with orbs, element balance, or fixed-star conjunctions within 1.5 degrees - List every transit-to-natal aspect, sign ingress, and station across a date window of up to 92 days - Compare two charts for synastry with inter-chart aspects, house overlays both ways, and a score per life sphere - Cast a solar return chart for a given year at the birth place or another location - Score each day in a window of up to 62 days for an activity such as business, romance, or travel and surface the five best days - Score a place against a chart or rank major cities worldwide or within a region such as Europe or Asia ## Use cases ### Astrology assistant agent with calculated charts An AI astrology assistant needs accurate positions rather than invented ones before it writes any interpretation. Through Jentic the agent searches for 'calculate a natal chart', loads the NatalChart.AI full chart operation with its input schema, and sends a birth object with date, time, latitude, and longitude. It receives every body's sign, degree, and house plus aspects with orbs, and grounds its reading in those numbers. The bearer key is attached by your own Jentic One instance at call time. Example prompt: Call POST `/v1/chart/full` with birth date 1991-09-06, time 18:30, latitude 50.4501, longitude 30.5234, then report the Sun, Moon, and Ascendant signs and degrees ### Transit calendar for a horoscope app A horoscope app shows users the exact dates when transiting planets aspect their natal chart. The transits operation takes a birth object plus from and to dates covering up to 92 days and returns exact transit-to-natal aspects by date, along with sign ingresses and stations, so the app can build a personal calendar without running an ephemeris itself. Example prompt: Call POST `/v1/transits` with a birth object and a window from 2026-12-01 to 2027-02-28, then list the exact aspects that fall in January ### Relationship compatibility with synastry A dating or relationship app compares two people's charts. The synastry operation takes personA and personB birth data and returns inter-chart aspects with orbs, house overlays in both directions, and a score for each life sphere, giving the app structured inputs for a compatibility view. Example prompt: Call POST `/v1/synastry` with personA and personB birth objects and summarize the three tightest inter-chart aspects by orb ### Electional timing and relocation A user planning a launch or a move wants dates and places that suit their chart. The timing operation scores every day of a window of up to 62 days for an activity such as business, travel, or home and lists the five best days first, while the locations rank operation orders major cities for one chart by chosen life spheres, worldwide or within a region. Example prompt: Call POST `/v1/timing` with activity 'business' for the next 60 days, then call POST `/v1/locations/rank` with region 'Europe' and limit 5 for the same birth data ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/chart/full` | Compute a full natal chart | | POST | `/v1/chart/short` | Compute the short chart | | POST | `/v1/transits` | List transits over a date window | | POST | `/v1/synastry` | Compare two charts | | POST | `/v1/solar-return` | Cast a solar return chart | | POST | `/v1/timing` | Score days for an activity | | POST | `/v1/locations/rank` | Rank cities for a chart | | GET | `/v1/sky` | Get the sky for a date | ## Key resources - **Chart** — Short and full natal charts and individual slices: planets, angles, houses, aspects, elements, and fixed stars - **Forecasting** — Transits over a date window, daily horoscope sky data, solar returns, and activity timing scores - **Synastry** — Two-chart comparison with inter-chart aspects, house overlays, and life-sphere scores - **Locations** — Relocated angles and scores for one place, and city rankings for a chart by region and life sphere - **Sky and usage** — Planetary positions and Moon phase for a date without birth data, plus plan and daily request count ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 45 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 74 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 20 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 68 / 100 - **View full report:** https://jentic.com/apis/natalchart.ai/natalchart/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring NatalChart.AI by hand means issuing a key from its developer page, sending it as a bearer token, and building the nested birth object with date, time, coordinates, and timezone for each operation. Through Jentic you install once, import NatalChart.AI from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** NatalChart.AI carries the birth data inside the request body, so rules bound which operations your agent may call rather than whose chart. Limit the agent to the operations it needs, such as the short chart or daily sky, so quota-heavy calls like transits or city ranking are not included unless you add them. - **Credential handling:** Your NatalChart.AI key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'calculate a natal chart' or 'find the best days for travel', and Jentic returns the matching NatalChart.AI operation with its input schema so the agent sends a correctly shaped birth object. ## Related APIs - **Free Horoscope & Tarot API** — Ready-written daily, weekly, and monthly horoscope text by sign rather than calculated personal charts - **Astronomy API** — Astronomical positions of celestial bodies, events, and rendered star charts without astrological interpretation - **OpenCage Geocoder** — Converts a birth place name into the latitude and longitude NatalChart.AI requires ## FAQ ### What authentication does the NatalChart.AI API use? Per its OpenAPI spec, the NatalChart.AI API uses HTTP bearer authentication: you send the API key issued on the NatalChart.AI developer keys page in the Authorization header as a bearer token. Through Jentic the key is stored encrypted by your own instance and attached per call, so it never appears in the agent's context. ### What birth data does the NatalChart.AI API need? Chart operations take a birth object with a required date (YYYY-MM-DD, 1800 to 2399), latitude, and longitude, plus an optional local time in HH:mm and an optional IANA timezone. If time is null the chart is computed for noon and time-dependent values are withheld; if timezone is left out it is resolved from the coordinates. ### What are the rate limits for the NatalChart.AI API? The spec's API description states the free plan allows 10 requests a day and API Pro allows 1000 requests a day for $6.99 a month. GET `/v1/usage` returns your plan, today's count, and when the pool refills, and does not count against the limit. ### Is there a NatalChart.AI MCP server? You don't need an MCP server to give your agent NatalChart.AI. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the chart, transit, and synastry operations it needs, discovered on demand rather than loaded into its context up front. ### How do I calculate a natal chart with the NatalChart.AI API through Jentic? Import NatalChart.AI from the API Directory in your Jentic One instance and store your key. Your agent searches for 'calculate a natal chart', loads POST `/v1/chart/full`, and sends the birth date, time, latitude, and longitude. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the NatalChart.AI API? Yes. Write a rule that allows only POST `/v1/chart/short` and GET `/v1/usage`, and the agent can return a quick Sun, Moon, and Ascendant reading and check its remaining quota, but cannot run the heavier transit, timing, or city-ranking calculations that spend the daily request pool. Every call it makes is logged.