Metadata-Version: 2.4
Name: astroapi-io-client
Version: 0.2.3
Summary: Synchronous Python client for the AstroAPI.io calculation gateway
License-Expression: ISC
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: receipts
Requires-Dist: cryptography<48,>=42; extra == "receipts"
Dynamic: license-file

# AstroAPI.io Python client

The R196 source version `astroapi-io-client==0.2.3` covers all forty-four calculation routes: forty-three standard operations plus the separate Pro Nakshatra Timeline. Minor-body calculations are not part of the contract.

A synchronous client for Python 3.10+, with no runtime dependencies.
The package import is `astroapi_client`; the distribution name is
`astroapi-io-client`. Version 0.2.2 is the published R195 package; 0.2.3 is source-only and package availability never implies deployed API capabilities.

Install from PyPI with `python -m pip install astroapi-io-client==0.2.2`, or from a local checkout using `python -m pip install ./clients/python`.
Building needs setuptools and wheel; the installed client uses only the standard
library. Keep API credentials in trusted server or command-line environments.

```python
from astroapi_client import AstroAPIClient, HTTPError, RequestTimeoutError

# Reads ASTROAPI_KEY; alternatively pass api_key=your_key explicitly.
client = AstroAPIClient()
birth = {
    "date": "1990-01-01",
    "time": "12:00",
    "timezone": "America/New_York",
    "lat": 40.7128,
    "lon": -74.006,
}

try:
    result = client.birth_chart(birth)
    sun = result["chart"]["planets"]["Sun"]
except HTTPError as error:
    print(error.status, error.retry_after)  # Sanitized; does not trigger a retry.
except RequestTimeoutError:
    print("Deadline exceeded; this request may already have consumed quota.")
```

An explicit key takes precedence over `ASTROAPI_KEY`. Keys must contain exactly
64 hexadecimal characters. The SDK never reads another application's settings,
environment files, browser sessions, or stored keys. Do not place keys in source
control, browser code, URLs, or logs.

## Methods and current response shapes

Each method takes one dictionary using the gateway's field names. It returns
the **complete parsed JSON object without changing its envelope**. Exported
`TypedDict` input types and `py.typed` support editors. Methods without a detailed response type return
`dict[str, Any]` (`JSONResponse`). `lunar_nodes`, `returns`, `solar_arcs` and
`vimshottari` provide detailed response type hints; Vimshottari is a union of
`VimshottariResponseDepth2`, `VimshottariResponseDepth3`, and
`VimshottariResponseDepth4`. The return's existing
nested chart remains `JSONResponse`.
Type hints describe the server contract and do not perform response validation.

| Method | OpenAPI operation ID | Input | Important response path |
|---|---|---|---|
| `birth_chart` | `calculateBirthChart` | Birth fields; optional zodiac/ayanamsa | `result["chart"]` |
| `place_search` **beta** | `searchPlaces` | Query; optional uppercase country codes and limit | Ordered versioned candidates in `result["results"]` |
| `timezone_resolve` **beta** | `resolvePlaceTimezone` | Versioned place ID plus local date/time | Explicit civil-time status/candidates and unique `resolved_input` |
| `natal_context` **beta** | `calculateNatalContext` | Birth; optional zodiac/ayanamsa/houses/formats | Stable facts, calculation hash, and selected text artifacts |
| `aspects` | `calculateAspects` | `{"birth": birth}`; optional zodiac/ayanamsa | `result["aspects"]["aspects"]` is the array |
| `houses` | `calculateHouses` | `{"birth": birth, "system": "whole_sign"}`; optional zodiac/ayanamsa | Full chart at top level; `result["houses"]["systems"]` |
| `synastry` | `calculateSynastry` | `{"personA": birth, "personB": other}`; optional zodiac/ayanamsa | `result["charts"]`, `result["aspects"]` |
| `transits` | `calculateTransits` | Birth plus required `transitDate`; optional `transitTime`, timezone, zodiac/ayanamsa | `result["transits"]["natal_chart"]`, `transit_chart`, `aspects` |
| `horoscope` **beta** | `calculateHoroscope` | Birth plus optional transit fields, timezone, zodiac/ayanamsa | `result["interpretation"]` |
| `nakshatra_timeline` | `calculateNakshatraTimeline` | Planet, `start_utc`, `end_utc`, ayanamsa | `result["segments"]` |
| `natal_svg` **beta** | `calculateNatalSvg` | Birth; optional zodiac, ayanamsa, houses/theme/show_aspects, named aspect profile or custom aspects, `include_png` | `result["svg"]`, optional `result["png"]` |
| `vargas` **beta** | `calculateVargas` | Birth; optional ayanamsa and one of twenty-four divisions through D150 | `result["bodies"]["moon"]["sign"]`, `result["ascendant"]` |
| `vimshottari` **beta** | `calculateVimshottari` | Birth; optional ayanamsa and depth 2/3/4 | `result["birth_balance"]`, `result["periods"]` |
| `ashtakoota` **beta** | `calculateAshtakoota` | Required groom/bride births; optional ayanamsa | `result["kootas"]`, `result["total"]`; no verdict/advice |
| `ashtakavarga` **beta** | `calculateAshtakavarga` | Required birth; optional ayanamsa and `include_reductions` | BAV, Prastara, SAV, and opt-in reductions/pindas; no interpretation |
| `numerology` **beta** | `calculateNumerology` | Gregorian `birth_date`; optional ASCII `name`, boolean `master_numbers`/`y_vowel`, integer `year` | `numbers` contains symbolic reduction traces; no interpretations or predictions |
| `composite` **beta** | `calculateComposite` | personA/personB; optional zodiac/ayanamsa/house_system | `result["planets"]`, synthetic `result["houses"]` |
| `panchang` **beta** | `calculatePanchang` | at civil snapshot; optional ayanamsa | `result["vara"]`, `result["solar_events"]` |
| `secondary_progressions` **beta** | `calculateSecondaryProgressions` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["progressed_planets"]`, separate natal_context |
| `varga_svg` **beta** | `calculateVargaSvg` | birth; optional ayanamsa/division/layout/theme/`include_png` | `result["svg"]`, `result["chart"]`, optional `result["png"]` |
| `lunar_nodes` **beta** | `calculateLunarNodes` | at civil instant without coordinates; optional zodiac/ayanamsa | `result["mean"]["north"]`, `result["true"]["north"]` |
| `returns` **beta** | `calculateReturns` | birth, body sun/moon, after civil time; optional zodiac/ayanamsa/house_system/location | `result["return_utc"]`, `result["chart"]`, `result["search"]` |
| `solar_arcs` **beta** | `calculateSolarArcs` | birth and target civil time; optional zodiac/ayanamsa/house_system | `result["arc"]`, `result["directed_planets"]`, `result["directed_angles"]`, `result["directed_houses"]` |
| `moon_phases` **beta** | `calculateMoonPhases` | instant `at` or calendar civil `start`/`end`; optional display timezone and `include_ical` | `result["result"]["phase_sector"]` or `result["result"]["events"]`; optional `result["result"]["ical"]` |
| `planetary_events` **beta** | `calculatePlanetaryEvents` | whole-second UTC interval, event types/bodies; optional aspects/zodiac/ayanamsa | `result["result"]["events"]` |
| `house_ingresses` **beta** | `calculateHouseIngresses` | reference birth, whole-second UTC interval, bodies; optional Equal/Whole Sign and zodiac/ayanamsa | `result["result"]["events"]`, fixed cusps |
| `aspect_windows` **beta** | `calculateAspectWindows` | whole-second UTC interval, bodies; optional aspects/orb/zodiac/ayanamsa/iCalendar | `result["result"]["windows"]` |
| `event_calendar` **beta** | `calculateEventCalendar` | whole-second UTC interval and selected event families | `result["result"]["events"]`; optional iCalendar, strict opt-in fixed-column CSV, and opt-in deduplicated pass groups |
| `event_rule_search` **beta** | `calculateEventRuleSearch` | bounded versioned AND/OR/NOT rules, location, and interval | validation/cost analysis plus sampled matches and windows |
| `convention_compare` **beta** | `calculateConventionCompare` | two profiles with one birth, or two trusted signed responses | field-level differences without ranking or interpretation |
| `chart_robustness` **beta** | `calculateChartRobustness` | unknown or approximate birth time plus 2–3 convention profiles | sampled stability classifications without rectification, ranking, or prediction |
| `civil_time_audit` **beta** | `calculateCivilTimeAudit` | pinned place, local date/time, one explicit profile | both repeated-time chart candidates and exact 22-fact differences, or no shifted gap time |
| `synastry_svg` **beta** | `calculateSynastrySvg` | two births; optional zodiac/houses/theme/aspects/`include_png` | `result["svg"]`, optional `result["png"]` |
| `transit_svg` **beta** | `calculateTransitSvg` | birth and transit date; optional display controls/`include_png` | `result["svg"]`, optional `result["png"]` |
| `natal_report` **beta** | `calculateNatalReport` | birth; optional zodiac/houses/theme/SVG/download | `result["html"]`, source-linked `result["facts"]`, optional `result["download"]` |
| `birth_time_sensitivity` **beta** | `calculateBirthTimeSensitivity` | civil interval up to six hours, or explicit unknown/approximate time, plus coordinates | `result["result"]["samples"]`, optional workflow classification |
| `fixed_stars` **beta** | `calculateFixedStars` | civil instant and 1–6 documented stars | `result["objects"]`; no minor bodies |
| `relocation_chart` **beta** | `calculateRelocationChart` | birth and destination coordinates; optional zodiac/ayanamsa/houses | `result["natal_reference"]`, `result["relocated_chart"]` |
| `astrocartography` **beta** | `calculateAstrocartography` | civil instant, 1–10 unique Sun-through-Pluto bodies, optional `include_geojson`, `include_geojson_seq`, `include_ndjson`, `include_topojson`, `include_kml`, `include_gpx`, `include_csv`, `include_wkt`, `include_wkb`, `include_gml`, `basemap`, `include_svg`, `include_png`, and `theme` | bounded geometry plus optional deterministic RFC 7946 GeoJSON, RFC 8142 GeoJSON Text Sequences, newline-delimited GeoJSON Features, unquantized TopoJSON, OGC KML 2.2, GPX 1.1, RFC 4180 CSV, WKT, WKB, GML 3.2 artifacts, and 1200×800 SVG/PNG coordinate-grid or bundled Natural Earth coastline map |
| `eclipse_geometry` **beta** | `calculateEclipseGeometry` | whole-second UTC interval up to 366 days, selected solar/lunar types, optional WGS84 observer | global events and optional sea-level/no-refraction snapshot in each event |
| `electional_search` **beta** | `calculateElectionalSearch` | location, one or more AND-only filters, and UTC interval up to seven days | hourly matches and sampled windows |
| `natal_analysis` **beta** | `calculateNatalAnalysis` | birth, aspect controls, and strict sidereal graha-drishti or partial-Shadbala opt-ins | aspects/patterns plus optional `graha_drishti` or `shadbala_foundation` |
| `planetary_hours` **beta** | `calculatePlanetaryHours` | civil date, IANA timezone, and coordinates | twenty-four unequal day/night temporal hours and rulers |
| `davison` **beta** | `calculateDavison` | personA/personB; optional zodiac/ayanamsa/house_system | `result["chart"]`, `result["midpoint"]`, `result["metadata"]` |

The never-live extended-sky methods were retired rather than depend on licensed
minor-body source data. They are not SDK methods or API contracts.

Graha drishti is a separate opt-in on `natal_analysis`. Exact `True` requires
explicit `zodiac: "sidereal"`; omission/false preserves the existing response.
Ruleset `parashari_whole_sign_full_aspects_v1` includes Sun, Moon, Mars,
Mercury, Jupiter, Venus, and Saturn only. It returns full whole-sign targets and
occupying classical grahas, with no node aspects, partial strengths, or
interpretation. The request remains one standard quota unit.

Synastry cross-aspects retain `transit` for person B and `natal` for person A.
The horoscope route is a beta, deterministic structured interpretation; it is
not a stable prose-report or LLM contract. Birth-chart/aspects compute both
legacy house systems; the houses method filters to the requested system.
Its `placidus`, `porphyry`, `meridian`, `campanus`, `regiomontanus`,
`alcabitius`, `koch`, `morinus`, `topocentric`, `sripati`, `vehlow`, `horizon`, `krusinski`, `sunshine`, `sunshine_alt`, `savard`, `pullen_sd`, `pullen_sr`, `carter`, `apc`, `equal_mc`, and `natural` options are beta, with explicit rejection and no fallback. Gauquelin is Houses-only because its response contains 36 sectors; natal
SVG accepts the preceding twelve-house systems, while other chart/report routes do not accept
Porphyry, Meridian, Campanus, Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, or Natural. Meridian cusp 1 is
the Equatorial Ascendant; Campanus, Regiomontanus, Alcabitius, and Koch cusp 1
are the physical Ascendant. Morinus cusps are latitude-independent; its cusps 1 and 10 are not the physical Ascendant and Midheaven. Topocentric uses Polich/Page house geometry with the physical Ascendant and Midheaven as cusps 1 and 10; it does not alter planet positions. Sripati shifts each cusp to the midpoint of the preceding Porphyry sector; its cusps 1 and 10 are not the physical angles. Vehlow uses twelve equal 30-degree ecliptic houses with the physical Ascendant at the center of house 1; its cusps 1 and 10 are not the physical angles. Horizon/Azimuth projects twelve equal local-horizon divisions through vertical circles to the ecliptic; cusp 1 is not the physical Ascendant and cusp 10 is the Midheaven. Krusinski-Pisa-Goelzer projects twelve equal Ascendant-zenith great-circle divisions through celestial meridian circles; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine uses the Treindl construction from trisected solar diurnal and nocturnal semi-arcs; cusps 1 and 10 are the physical Ascendant and Midheaven. Sunshine alternative uses the separate Makransky prime-vertical projection for the same solar house points. Savard-A projects one-third and two-thirds geographic-latitude circles through the prime vertical; cusps 1 and 10 are the physical Ascendant and Midheaven and opposite cusps are antipodal. Pullen SD redistributes each ecliptic quadrant's deviation from 90 degrees with quarter/half/quarter weighting; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Pullen SR proportions complementary quadrant house widths as rx, x, rx and r³x, r⁴x, r³x; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Carter divides right ascension into twelve equal arcs from the orientation-adjusted Ascendant and projects them to the ecliptic; cusp 10 is not generally the physical Midheaven. APC divides the Ascendant parallel into six sectors below and six above the horizon; cusps 1 and 10 are the orientation-adjusted angles and intermediate opposite cusps are not generally antipodal. Equal MC fixes the physical Midheaven at cusp 10 and places twelve equal 30-degree ecliptic houses; cusp 1 is generally not the physical Ascendant. Natural fixes cusp 1 at zero degrees Aries in the selected zodiac and places all cusps on sign boundaries; physical angles remain separate. Gauquelin is Houses-only and returns 36 clockwise semiarc sector boundaries under the existing houses map; sector 1 is Ascendant and sector 10 is Midheaven. Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter, APC, Equal MC, Natural, and Gauquelin are not admitted by saved
profiles. Equal/Whole Sign remain the existing chart defaults.

```python
timeline = client.nakshatra_timeline({
    "planet": "moon",
    "start_utc": "2026-01-01T00:00:00Z",
    "end_utc": "2026-01-03T00:00:00Z",
    "ayanamsa": "lahiri",
})
```

The timeline is Pro-only, always sidereal, supports the nine documented bodies,
and allows a positive range up to 180 days. It uses a separate quota. It does not
accept a sampling-step override. Dates across routes remain limited to
1900–2050. Legacy chart nodes and timeline Rahu/Ketu remain mean-node calculations;
the separate `lunar_nodes` beta supplies a distinct geometric osculating model.
Installing the SDK does not change any existing calculation convention or accuracy.

The SVG route accepts birth data, not an uploaded chart, SVG, URL, font or image.
Defaults are Equal houses, light theme, major aspects shown, tropical zodiac
and Lahiri when sidereal. The result contains an SVG string inside JSON; it is
not a browser credential or hosted-widget API.

Natal, synastry, transit and varga SVG plus natal report accept exact `light`,
`dark`, or `monochrome`. Defaults are unchanged. Monochrome is a fixed
grayscale palette, not an accessibility certification; optional PNG pixels are
grayscale while retaining RGB encoding.

Natal report HTML accepts optional `report_branding` with a required 1–64 character bounded ASCII `display_name` and optional exact `amber`, `blue`, or `green` accent. It is escaped, text-only, visibly attributed to AstroAPI, and invalid with non-HTML formats; omission preserves exact predecessor bytes. No logo, URL, markup, template, remote resource, localization, or fact mutation is accepted.

Natal report downloads accept exact `include_download: True`. Omitted
`download_format` retains HTML; exact `pdf`, `docx`, `xlsx`, `ods`, `epub`, `odt`, `rtf`, `json`, `csv`, `xml`, `ndjson`, `tsv`, `markdown`, `text`, or
`zip` selects deterministic PDF, editable macro-free OOXML, editable
macro-free and formula-free OOXML workbook, macro-free ODF 1.3, editable dependency-free RTF, machine-readable JSON, tabular CSV, fixed-order XML, canonical one-record-per-fact NDJSON, escaped fixed-column TSV, UTF-8 calculation facts/plain text, or the unchanged fixed
HTML/PDF/calculation-JSON bundle.

Vargas and Vimshottari always use sidereal coordinates with Lahiri default.
Vargas supports D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 (default D9) for nine traditional bodies plus the
Ascendant, not outer planets. Vimshottari returns nine major periods, each with
nine subperiods, using a fixed 365.25-day Julian year. Its first period begins
at the theoretical natal-major start, which can precede birth. Arithmetic
schedule dates may extend outside the ephemeris input-date window; they are
not predictions or additional ephemeris calculations. Optional `depth: 3` adds
one fixed third level; omission or `depth: 2` preserves the original response.
No arbitrary depth,
year model, range or specialist signoff is claimed. Each of these beta routes
costs one standard-call unit under unchanged plan quotas/prices and uses the
normal request deadline.

## Validation, deadlines and errors

The client checks required fields, supported enums, numeric coordinate bounds,
date/time formats, timeline ranges and the 128 KiB request limit before sending.
It accepts JSON numbers for coordinates and documented lowercase enum values;
unknown fields and explicit null optionals are rejected. Omit unused optional
fields. Timezone identifiers, DST ambiguity/nonexistence and undefined
Ascendant geometry remain server validation. Supplying a known UTC instant
avoids ambiguous local clock changes. No defaults are inserted into payloads.

Normal requests have a 20-second caller deadline; planetary events, eclipse geometry, electional search, event rules and aspect windows have 35 seconds; timelines and birth-time sensitivity have 70 seconds.
Configure `timeout=`, `planetary_events_timeout=`, and `timeline_timeout=` with finite positive seconds up to
300. The deadline covers network establishment, TLS, headers, response body and
JSON parsing, but starts after local input validation/serialization.

The synchronous call uses a daemon transport worker so a stalled operating-system
DNS lookup or slowly arriving headers/body cannot keep the caller waiting past
its deadline. Cancellation shuts down the known socket. A DNS call itself
cannot be forcibly stopped; its worker retains a slot until it exits and checks
cancellation before sending credentials. There are at most eight outstanding
transport workers **across all client instances in a process**. Exhaustion raises
`ClientBusyError` without starting another request. No context manager or explicit
close is needed; every completed exchange closes its connection. Successful
calls do not reuse connections.

`max_response_bytes=` defaults to 4 MiB and may be set from 1 byte through 64 MiB.
Oversized, truncated, compressed, non-object, duplicate-key or malformed JSON
responses are rejected. Bodies are read incrementally; compressed responses are
not decompressed. The standard library also limits HTTP header count and line
length. Errors omit request payloads, response bodies, credentials, raw headers,
and underlying transport exceptions. `HTTPError` exposes only numeric `status`
and sanitized `retry_after` (integer seconds or a normalized HTTP date).

There are **no automatic retries**, including for 429, 503 or timeouts. Once the
gateway reserves quota, even an invalid payload, dependency failure or timeout
consumes a unit. A client disconnect does not cancel admitted server work.

## Transport origin

The default is `https://api.astroapi.io`; calls use `POST /api/astro/...` with
`Authorization: Bearer`. A custom `base_url` must be a trusted HTTPS origin
without a path, credentials, query or fragment. Selecting another HTTPS origin
authorizes sending your key to that origin. TLS certificates and hostnames are
verified. Proxy environment variables, cookies and redirects are not used.
Every redirect is returned as `HTTPError`; keys are never forwarded to its
destination.

For local Node gateway testing only:

```python
client = AstroAPIClient(
    api_key=your_synthetic_key,
    base_url="http://127.0.0.1:5100",
    allow_http_localhost=True,
)
```

HTTP requires explicit opt-in and both a loopback/localhost URL and a loopback
connected peer. Never point the client directly at the internal Python engine.

## Offline checks

From this directory, after local installation:

```sh
python -m unittest discover -s tests -v
```

Tests use generated synthetic keys and local HTTP/HTTPS servers. Real TLS tests
generate temporary certificates with local OpenSSL and explicitly skip if it is
unavailable; no certificate keys are committed. They do not call the
production API or Stripe. The example under `examples/` makes a billable API
request when explicitly run with a real key. Its executable-example test replaces
the transport with a local mock and uses no real account key.

## Additional bounded beta calculations

- Composite: strict personA/personB birth objects; shortest-arc planetary and angle midpoints. Equal/Whole Sign houses are synthetic from midpoint Ascendant, not physical/Davison houses. Near-antipodal sources reject; no Placidus, nodes or speeds.
- Panchang: strict at civil snapshot and optional ayanamsa, always sidereal. Latitude is inclusive [-88,88]. Classifications are at the requested instant; solar events use the USNO -50 arcminute horizon at elevation 0, not Hindu-geocentric sunrise. Civil weekday and sunrise-based vara differ. Unavailable bounded sunrise gives explicit null vara. Historical local offsets can include seconds; paired UTC fields are interoperable.
- Secondary progressions: strict birth plus target date/time/timezone, target>=birth. Planets only, fixed 365.2421904-day year in uniform TT; natal_context angles/houses are not progressed. Derived progressed_utc may contain actual leap second 60; preserve the string rather than passing it blindly to JavaScript Date/Python datetime. No progressed angles/houses/aspects/nodes/speeds or prediction claim.
- Varga SVG: birth plus optional ayanamsa, any supported D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 division, layout north_indian/south_indian and theme light/dark/monochrome. Defaults D1/north_indian/dark; /vargas instead defaults D9. Original North fixed-house/South fixed-sign SVG, houses counted from divisional Ascendant; not bhava-chalit. Response.chart is the unchanged Vargas result; SVG is bounded to 128 KiB inside JSON.
  D150 additionally accepts exact `d150_method` values `"deva_keralam_chandra_kala_nadi_non_uniform"`, `"deva_keralam_chandra_kala_nadi_uniform_direct"`, `"parivritti_cyclic"`, `"movable_aries_forward_fixed_taurus_reverse_dual_gemini_forward"`, `"movable_aries_forward_fixed_scorpio_reverse_dual_sagittarius_forward"`, `"movable_aries_forward_fixed_leo_reverse_dual_sagittarius_forward"`, and `"movable_source_sign_forward_fixed_source_sign_reverse_dual_source_sign_forward"`; omission retains the uniform-direct D150 response, and the field is rejected for every other division.

- Lunar nodes: `lunar_nodes` takes an `at` civil instant with no coordinates and optional zodiac/ayanamsa. The response provides north/south pairs for Meeus mean nodes and geometric DE421 osculating nodes, each with its explicit source frame. `LunarNodesInput` and `LunarNodesResponse` are exported types. Chart and timeline node fields keep the existing mean-node contract.
- Returns: `returns` takes birth, exact body `sun` or `moon`, and an `after` civil instant. Optional zodiac/ayanamsa, Equal/Whole Sign houses and `location:{lat,lon}` are supported; location defaults to birth coordinates. `ReturnsInput` and `ReturnsResponse` type the new request/envelope. Read `return_utc`, `chart` and `search`. The first return lies beyond a one-millisecond start exclusion and the full fixed 370-day Sun/32-day Moon TT window must fit the supported UTC range. `after` may precede birth. Preserve leap-second UTC strings; numerical tolerance does not establish physical accuracy.

- Solar arcs: `solar_arcs` takes strict birth plus target civil time and optional zodiac/ayanamsa/Equal or Whole Sign houses. Omitted `method` and exact `true_solar_arc` preserve the direct true tropical Sun arc. Exact `method: "mean_naibod"` applies the fixed 0.98564733° mean longitude key per elapsed 365.2421904-day TT model year. Both methods direct natal planets and Ascendant/MC uniformly and retain synthetic houses, one-unit accounting, the 1900–2050 dates, and natal-date ayanamsa policy. No relocation, converse/right-ascension arc, MC-derived angle recalculation, arbitrary key, aspects, nodes or speeds.
- Vimshottari depth: `depth` accepts integer 2, 3, or 4. Omission/2 and the complete depth-3 response remain unchanged. Depth 4 adds 6,561 Sookshma leaves, `birth_balance.sookshma_dasha_lord`, and exact count metadata. Fourth-level leaves omit the redundant display-only `years` field so the complete response stays below 1 MiB. Python rejects floats, strings and booleans. Depth 4 is synchronous-only under the durable-job 256 KiB cap. The arithmetic is bounded and deterministic, not arbitrary recursion or prediction; an admitted synchronous call costs one standard unit.
- Eclipse geometry: `eclipse_geometry` searches at most 366 UTC days. Optional `observer` coordinates add a fixed sea-level, no-refraction topocentric snapshot at each rounded global maximum. It does not calculate the location's maximum, contacts, visibility at other instants, paths, maps, terrain/weather, safety guidance or interpretation.
- Electional search: `electional_search` applies one or more documented AND-only filters at fixed hourly samples for at most seven days/168 samples. Results are sampled candidates without continuous guarantees, ranking, recommendations, void-of-course analysis or interpretation.
- Natal analysis: `natal_analysis` returns configured aspects, optional midpoint axes, and geometric Grand Trine, T-square, Grand Cross, and Yod matches for selected Sun-through-Pluto points. `additional_points` may explicitly select Vertex/Antivertex, Equatorial Ascendant/Descendant, and Lots of Fortune/Spirit; they stay separate from aspects and interpretation.
- Planetary hours: `planetary_hours` returns twelve daylight and twelve nighttime unequal temporal hours with Chaldean rulers. It requires a complete sunrise-sunset-next-sunrise sequence and supplies no electional advice.

All thirty deployed additive beta routes reserve one standard-call unit, accept only exact documented fields/enums, and retain existing prices, quotas and no automatic retry. Practitioner sign-off and a complete astrology catalogue are not claimed.

### Aspect windows beta

Use `client.aspect_windows(...)` for exact-hit-anchored major-aspect orb intervals, repeat numbering, clipped boundaries and optional RFC 5545 text. Inputs span at most 31 UTC days and use a 35-second default deadline.
