AstroAPI.io Python client

The R202 source client astroapi-io-client==0.2.10 covers all fifty calculation routes: forty-nine standard operations plus the separate Pro Nakshatra Timeline. This package version is the verified R202 client publication; service availability still requires R202 promotion. 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.10 is the R202 source client; package availability never implies that source-only R202 API capabilities are deployed.

Install from PyPI with python -m pip install astroapi-io-client==0.2.10, or install the R202 source 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.

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.

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.

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:

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:

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.