PRIMARY tool for any natal/birth-chart request. Renders an interactive, clickable chart wheel — prefer this over ephemeris_natal_chart when the user wants to SEE a chart. Returns an embedded visual chart explorer that lets you click any planet, house, or aspect line for instant astrological interpretation.

CREDIT COST: 1 credit per call.

Supports house system switching (Placidus, Whole Sign, Equal, Koch). The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. Renders interactively in MCP Apps-capable hosts (Claude Desktop) and falls back to static SVG in other hosts.

Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.

CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the visual), 2 in text-only hosts that skip the render. For chart data alone at 2 credits — including the activations, design, personality, strategy and variables this tool does not return — use human_design_chart.

Returns an embedded visual bodygraph explorer that lets you click any center or gate for instant Human Design interpretation. Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, and Incarnation Cross. The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. Use this instead of human_design_chart for a richer, interactive HD experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph.

CREDIT COST: 3 credits per call.

Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it newly defines — the core of a Human Design transit reading. Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude Desktop), with a text summary fallback elsewhere. Premium (Pro tier). Calculated with NASA JPL DE440 ephemerides. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

Compare two people's Human Design charts and classify every connected channel by HD connection theory.

CREDIT COST: 3 credits per call.

Classifications: electromagnetic (attraction), companionship (sameness), dominance (one defines), and compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

Generate an interactive bi-wheel chart comparing two astrological chart positions.

CREDIT COST: 2 credits per call for most modes (1 per wheel computed); solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel).

The inner wheel is always Person 1's natal chart. The outer ring depends on mode: • synastry — Person 2's natal chart (needs Person 2's own birthplace). • transit — Transiting planets for a given date. • progressed — Secondary progressed positions (person2_datetime = target date). • solar_return — Nearest solar return chart (person2_datetime = year to return for). • lunar_return — Nearest lunar return chart (person2_datetime = target month). • solar_arc — Solar arc directed positions (person2_datetime = target date). Cross-aspects are drawn as coloured dashed lines; click any planet, aspect line, or house cusp for interpretation. Prefer this whenever the user should SEE the comparison — it renders interactively in MCP Apps hosts and falls back to static SVG elsewhere. For raw synastry data without a visual, use ephemeris_synastry.

Generate an interactive Moon Phase dial showing the current lunar illumination, phase name, zodiac sign, and void-of-course status as a beautiful circular visualization.

Returns a visual dial with: • SVG crescent Moon showing real-time illumination percentage • Phase name and waxing/waning indicator • Current Moon sign with degree • Void-of-Course status with timing details • Lunar age (days in the synodic cycle) • Upcoming New Moon and Full Moon dates

CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).

Use this instead of ephemeris_moon_phase for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.

Generate an interactive Transit Timeline — a vertical, date-ordered list of upcoming transit hits (transiting planets forming a chosen aspect to natal chart positions) over a date range.

Returns a visual timeline with: • Exact crossing dates grouped by month • Transiting planet glyph, the natal point it contacts, and the aspect • Zodiac position of each crossing and retrograde markers • Click any transit for a focused interpretation

ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. DEFAULT natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.

CREDIT COST: 6 credits per call (natal chart + predictive transit search).

Use this for a rich, interactive transit-forecast experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.

Generate an interactive Vedic (Jyotish) birth chart as a South Indian fixed-sign Rashi grid, with clickable rashis showing sidereal placements, nakshatras, and the Lagna.

CREDIT COST: 3 credits per call (chart calculation + visual render).

Returns an embedded visual explorer that lets you click any rashi cell for its themes and any planets placed there. Shows sidereal (Lahiri by default) planet placements, nakshatra with pada, navamsa, and the Lagna (Ascendant) rashi. Uses NASA JPL DE440 ephemerides. Use this for a rich, interactive Jyotish experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.

Look up the sexagenary pillar for any Gregorian year (1–9999). Returns the Heavenly Stem, Earthly Branch, Chinese characters, zodiac animal, element, polarity, and NaYin (纳音) poetic resonance image.

NaYin maps each pair in the 60-cycle sexagenary sequence to one of 30 elemental images (e.g. '海中金 Metal in the Sea', '炉中火 Fire in the Furnace'). It is traditionally applied to the Year and Day pillars to reveal deeper elemental character.

Use this to: • Identify the energetic quality of any given year • Determine a person's birth year pillar for compatibility context • Find the NaYin element for year or day interpretations

CREDIT COST: 3 credits per call.

EXAMPLE: Year pillar for 2025: year=2025

Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars.

Returns an embedded visual Four Pillars explorer showing the Year, Month, Day, and Hour pillars — each with its Heavenly Stem (天干) and Earthly Branch (地支), Ten God label, and element color — plus the Day Master identity and a Wu Xing (五行) element balance bar. Click any pillar for an instant interpretation of what it reveals about that life domain (Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).

CREDIT COST: 3 credits per call (1 base + 2 visual render).

Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts, so it is also the right call without a renderer. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain non-visual pillars lookup have dedicated tools on the full surface (?profile=full).

Start the device authorization flow to connect this MCP server to your OpenEphemeris account (free tier, no credit card needed). Returns a verification URL and code for the user to enter in their browser. The MCP server will then automatically receive credentials and all API calls will be linked to the user's account (tier, credits, rate limits). Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.

Check the current authentication status of this MCP server. Shows whether the server is authenticated, which account it's linked to, the authentication method (API key, JWT, device auth), and token expiry.

Disconnect this MCP server from your OpenEphemeris account by clearing cached credentials. Does NOT revoke the API key if one is set via environment variable — only clears device-auth cached credentials.

Check the user's OpenEphemeris account usage and remaining credits. Returns their plan tier, billing period, credits used / included / remaining, percent of quota used, total API calls, and subscription status with renewal date.

✅ USE THIS TOOL FOR: 'How many credits do I have left?', 'What's my usage this month?', 'Am I close to my limit?', 'What plan am I on?', 'How do I upgrade or top up?'

CREDIT COST: Free (0 credits).

EXAMPLE: Check current usage: (call with no arguments)

EXAMPLE: Check a past month: month='2026-06'

Read from any allowlisted Open Ephemeris API endpoint via HTTP GET. This is the read-only power-user escape hatch — use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) first for common operations. Endpoints that compute via POST (natal-chart, synastry, etc.) are covered by the typed tools; the generic POST proxy is only exposed on the full tool surface (?profile=full).

Target API: Open Ephemeris REST API (https://api.openephemeris.com). Call dev_list_allowed to see all currently available endpoint paths.

AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.

CREDIT COSTS: • Standard chart math (natal, progressed, bazi, vedic, iching): 1 credit • Human Design: 2 credits • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits • Comparative math (synastry, composite, overlay): 3 credits • Predictive ops (transits/search, returns): 5 credits • Predictive transit-chart: 1 credit • ACG / astrocartography: 10 credits (acg/hits: 15 credits) • Calendar endpoints: 10 credits • Catalog / metadata / health endpoints: 0 credits • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional) • format=llm (token-optimized output): available on all tiers

COMMON CALLS: POST /ephemeris/natal-chart — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}}) POST /ephemeris/natal/batch — Up to 50 natal charts in one request POST /ephemeris/relocation — Relocated chart (same natal, new location) POST /predictive/transits/search — Transit event search over a date range POST /predictive/returns/solar — Solar return chart POST /predictive/returns/lunar — Lunar return chart POST /comparative/synastry — Two-person synastry chart POST /comparative/composite — Composite (midpoint) chart POST /human-design/chart — Full HD chart (body: {birth_datetime_utc: '1990-04-15T19:30:00Z'}) — lat/lon optional POST /time/julian-day — Convert date to JD (body: {year: 1987, month: 7, day: 15, hour: 14, minute: 1}) GET /ephemeris/moon/phase — Current/queried moon phase GET /ephemeris/moon/void-of-course — Next void-of-course period GET /ephemeris/agro/daily — Biodynamic farming day quality GET /ephemeris/agro/calendar — Multi-day biodynamic calendar GET /ephemeris/agro/void-of-course — Biodynamic VoC periods GET /eclipse/next-visible — Next eclipse visible from a location (query: lat, lon, type=solar|lunar) GET /eclipse/solar/global — Next global solar eclipse (query: date=YYYY-MM-DD) GET /eclipse/solar/local — Local solar eclipse (query: lat, lon) GET /tidal/forcing — Gravitational tidal forcing index POST /acg/power-lines — Astrocartography power lines (lat/lon GeoJSON) POST /acg/hits — ACG power at a specific location GET /calendar/astrology/moon-phases — Moon phase calendar for a date range GET /location/autocomplete — Geocode a place name (query: query=City Name) POST /timezone/lookup — Resolve timezone + UTC offset for a location POST /chinese/bazi — Chinese Ba Zi (Four Pillars) chart (body: {year, month, day, hour}) GET /chinese/zodiac — Chinese zodiac year element/animal POST /vedic/chart — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude}) GET /catalogs/bodies — List all supported celestial bodies

BINARY RESPONSES: • Binary/image endpoints return {content_type, content_length, encoding, data_base64} so callers can decode bytes deterministically.

ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.

format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for compact columnar output optimized for LLM token budgets (availability depends on your current plan).

List all API operations (method + path) that this MCP instance is authorized to call. Returns endpoint entries grouped by method, plus the active deny rules. Use this to discover what's available before calling dev_read_api, or to verify an endpoint path. Typed shortcut tools (ephemeris_natal_chart, ephemeris_transits, etc.) cover the most common operations — check those first before reaching for the generic proxies.

Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for interpretation (available on all tiers). The result includes all major planets, Chiron and major asteroids like Ceres, angles (ASC/MC/DSC/IC), essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included. Returns raw JSON. For a user-facing visual chart, use explore_natal_chart instead.

CREDIT COST: 1 credit per call.

EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago — pass the local time and name the zone: datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298 Equivalently, put the zone on the datetime: datetime='1990-04-15T14:30:00-05:00' (or the UTC instant '1990-04-15T19:30:00Z').

Search for astrological transit events affecting a natal chart over a date range. Returns exact transit moments — when transiting planets form specified aspects to natal planet positions.

EFFICIENCY TIP: Always specify both transiting_planets and natal_points to keep compute fast. Omitting both sends all outer planets against all core natal positions — a much heavier computation.

ASPECT ANGLES: Use aspect_angle to search for specific aspects: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. Example: Saturn Return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0 Example: Uranus Opposition → transiting_planets=['uranus'], natal_points=['uranus'], aspect_angle=180 Example: Outer planets to natal Sun/Moon → transiting_planets=['saturn','uranus','neptune','pluto'], natal_points=['sun','moon']

DEFAULT natal_points (when omitted): sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: Explorer/PayG tier → 1 year max; Pro → 5 years; Startup → 10 years. CREDIT COST: 6 credits per call.

Get the Moon's current phase angle, illumination, sign and void-of-course status AT a specific point in time. Returns phase name (New, Waxing Crescent, etc.), illumination %, the zodiac sign and degree the Moon occupies, and next void-of-course period.

⚠️ THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' and 'What sign is the moon in?' ❌ THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?' → For upcoming phase DATES use ephemeris_next_lunar_phase instead.

For a user-facing interactive moon-phase dial, use explore_moon_phase instead.

CREDIT COST: 2 credits — phase and void-of-course are metered separately. For phase alone at 1 credit, use dev_read_api path='/ephemeris/moon/phase'.

If no datetime is provided, returns the current (live) moon phase.

Find the next occurrence of a specific Moon phase after a given date. Returns the exact UTC datetime of each occurrence.

✅ USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', 'What date is the next quarter moon?', or any question about UPCOMING phase dates. ❌ NOT FOR: 'What phase is the moon in right now?' or 'What sign is the moon in?' → For the phase, sign and degree AT a moment, use ephemeris_moon_phase.

CREDIT COST: 1-2 credits per occurrence returned — each occurrence takes one calendar search, plus a second search when the first window misses. So count=3 costs 3-6 credits.

EXAMPLE: Find the next new moon: phase='new_moon'

EXAMPLE: Find the next full moon after a specific date: phase='full_moon', after_date='2026-06-01'

EXAMPLE: Find the next 3 full moons: phase='full_moon', count=3

Find the next solar or lunar eclipse. Returns the eclipse type, date/time of maximum, magnitude, and duration of totality (if any).

📍 LOCATION OPTIONAL: • WITH latitude+longitude → returns local contact times and visibility for that specific location. • WITHOUT latitude+longitude → returns the next global eclipse of that type (no location needed).

USE THIS TOOL FOR: 'When is the next solar eclipse?', 'When is the next total lunar eclipse?', 'Will there be an eclipse visible from Tokyo?'

CREDIT COST: 1 credit per call.

EXAMPLE: Next solar eclipse globally (no location needed): eclipse_type='solar'

EXAMPLE: Next solar eclipse visible from New York: eclipse_type='solar', latitude=40.7128, longitude=-74.006

EXAMPLE: Next lunar eclipse from London: eclipse_type='lunar', latitude=51.5074, longitude=-0.1278

Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type (Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.

Returns raw JSON. For a user-facing interactive bodygraph, use explore_human_design instead.

CREDIT COST: 2 credits per call.

Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion before birth (~3 months prior, the Design calculation). The API handles this automatically.

The datetime must state its zone — pass an offset/'Z', or pass local time plus timezone. A zone-less datetime is rejected rather than assumed to be UTC: Human Design is minute-sensitive, and an hour of error changes the Profile and the Design Sun line.

EXAMPLE (local birth time + zone): someone born 15 April 1990 at 14:30 in Chicago: datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298 EXAMPLE (already in UTC): datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298

Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects (planetary connections between the two charts), composite points, and relationship indicators. Use this for compatibility analysis, relationship timing, or partnership insights.

CREDIT COST: 3 credits per call.

EXAMPLE: Compare two people's charts (local birth times, each with its zone): person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago', person_a_latitude=41.8781, person_a_longitude=-87.6298, person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles', person_b_latitude=34.0522, person_b_longitude=-118.2437

Calculate a relocation chart — the same natal planetary positions re-cast for a different geographic location. Used to understand how living in a different city shifts house placements and angles, without changing the planetary longitudes in the chart.

CREDIT COST: 1 credit per call.

EXAMPLE: How does moving from Chicago to London change someone's chart? natal_datetime='1990-04-15T14:30:00', timezone='America/Chicago', natal_latitude=41.8781, natal_longitude=-87.6298, relocation_latitude=51.5074, relocation_longitude=-0.1278

Find optimal planetary timing windows (electional astrology). Scans a date range to find the best times for an event based on essential dignity, aspect quality, sect, and void-of-course moon penalties. Evaluates every hour and clusters the best continuous windows.

CREDIT COST: 5 credits per call (heavy calculation).

EXAMPLE: Find the best time to launch a business in early March 2026. start_date='2026-03-01', end_date='2026-03-10', latitude=40.7128, longitude=-74.0060, avoid_voc=true, lunar_phase='waxing'

Analyze the astrological quality of a specific moment: planet positions, aspects, void of course status, lunar phase, day ruler, and an overall electional score (0-100). Perfect for evaluating whether 'right now' or a specific date/time is good for action.

CREDIT COST: 5 credits per call.

EXAMPLE: Analyze March 21, 2026 at noon: date='2026-03-21T12:00:00Z'

Find all upcoming retrograde and direct stations for planets in a date range. Returns exact station times, longitudes, and signs.

USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', 'What planets station this month?', 'When does Mars go direct?'

❌ NOT FOR: 'Is Mercury retrograde right now?' — that is the state at a single instant, so use ephemeris_retrograde_status (1 credit for one planet, vs 5 here).

All required fields have smart defaults (searches the next 90 days from today).

CREDIT COST: 5 credits per call.

EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults): (no args required, will auto-scan next 90 days for all inner planets)

EXAMPLE: Outer planet stations in 2026: start_date='2026-01-01', end_date='2026-12-31', planets='jupiter,saturn,uranus,neptune,pluto'

Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements in rashis (sidereal signs), nakshatras with pada, navamsa placements, and bhavas (houses). Uses Whole Sign houses, sidereal zodiac with configurable ayanamsa.

CREDIT COST: 1 credit per call.

SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar

EXAMPLE: Vedic chart for someone born Jan 15, 1990 at 8:30 AM UTC in Mumbai: datetime='1990-01-15T08:30:00Z', latitude=19.076, longitude=72.8777

Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude (happens once per year near the birthday). Returns the Solar Return chart for the year ahead.

CREDIT COST: 5 credits per call.

TARGET DATE: Provide target_datetime near the desired birthday year. If omitted, defaults to the current year's solar return.

EXAMPLE: Solar return for someone born 1985-06-21 (current year): birth_datetime='1985-06-21T14:00:00Z'

EXAMPLE: Solar return for 2027 specifically: birth_datetime='1985-06-21T14:00:00Z', target_datetime='2027-01-01T00:00:00Z'

Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. Returns progressed planet positions, house cusps, aspects, and retrograde status.

CREDIT COST: 1 credit per call.

EXAMPLE: Secondary progressions for someone born 1985-06-21 at 2:00 PM in London, progressed to 2026-01-01: birth_datetime='1985-06-21T14:00:00', timezone='Europe/London', birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'

Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status for a single planet/body at a given date and time. Planet IDs: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.

SOUTH NODE: there is no South Node id. The South Node is always exactly opposite the North Node — request id 10 or 11 and add 180° (mod 360).

CREDIT COST: 1 credit per call.

EXAMPLE: Where is Mars on 2026-03-20 at noon UTC? planet_id=4, datetime='2026-03-20T12:00:00Z'

Calculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location using one or more house systems.

House system codes: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign.

CREDIT COST: 1 credit per call.

EXAMPLE: Placidus houses for London at 2026-03-20 noon UTC: datetime='2026-03-20T12:00:00Z', latitude=51.5074, longitude=-0.1278, house_systems=['P']

Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station proximity.

✅ Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; 'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns retrograde or direct, or whether it stations anywhere in a date range, use electional_station_tracker.

CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the all-planets sweep and costs 10 credits — the backend bills one credit per body and this fans out to 10. Only omit it when the question really is about every planet.

Calculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, East Point, etc.) for a given date/time and location.

CREDIT COST: 1 credit per call.

Check the aspect between two ecliptic longitudes. Returns the angular separation and any aspects within orb (conjunction, sextile, square, trine, opposition, etc.).

CREDIT COST: 1 credit per call.

EXAMPLE: Check aspect between 15° Aries and 75° Gemini: longitude_1=15, longitude_2=75

Calculate Astrocartography power lines (MC, IC, AC/ASC, DC/DSC) for a natal chart. Returns GeoJSON LineStrings tracing each planetary angle line around the globe. These are the latitudinal lines where a planet was rising (AC), setting (DC), culminating (MC), or anti-culminating (IC) at birth.

❌ NOT FOR: 'Is [city] good for me?' or 'What planets affect me in Tokyo?' → For a specific city/location analysis, use acg_hits instead (faster and more relevant). ✅ USE FOR: Getting the full global GeoJSON line geometry for map rendering or bulk geographic analysis.

CREDIT COST: 10 credits per call.

EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 at 2:30 PM in Chicago: birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago', birth_latitude=41.8781, birth_longitude=-87.6298, bodies=['Saturn', 'Jupiter']

Find all Astrocartography lines (power lines + aspect lines) passing near a specific location. Returns features sorted by distance, making it easy to interpret planetary influences at a place.

✅ USE THIS TOOL FOR: 'Is [city] good for me?', 'What planets affect me in Tokyo?', 'What ACG lines run through Paris for my chart?', 'Which cities are under my Jupiter line?' ❌ NOT FOR: Full global map geometry → use acg_power_lines for that instead.

CREDIT COST: 15 credits per call.

EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago: birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago', birth_latitude=41.8781, birth_longitude=-87.6298, query_latitude=48.8566, query_longitude=2.3522, radius_deg=3

Resolve a place name to coordinates and IANA timezone — use this first whenever a user gives a birth city rather than latitude/longitude. NEVER recall coordinates from memory; always resolve them here. CREDIT COST: 1 credit per call. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Pass the birth date as date to also get utcOffsetAtDate, the historically-correct UTC offset for that place on that date (1987 DST rules differ from today's) — this costs no extra credits. When the result is ambiguous (several places share the name, e.g. "portland"), ASK the user which one they mean rather than assuming the first. Optional bias params (country/region/near) improve ranking; a trailing "City, ST" qualifier in the query is also honored.

Resolve the IANA timezone for a latitude/longitude pair. Use when you have coordinates but need the timezone to interpret a local birth time. Pass date to also get the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call. If you are starting from a place name rather than coordinates, use location_search instead — it returns the timezone too, in the same single call.