dev_read_api

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).