--- title: "Cyclocartography Time-Series (Go Engine)" method: POST path: "/acg/ccg" tags: ["ACG"] --- # Cyclocartography Time-Series (Go Engine) `POST /acg/ccg` ## Request - Base URL: `https://api.openephemeris.com` - URL: `https://api.openephemeris.com/acg/ccg` - Auth: one of: - HTTP bearer - API key in header `X-OpenEphemeris-API-Key` - API key in header `X-API-Key` - API key in header `X-Service-Key` Compute cyclocartography transit snapshots over a time window. ## Request body - ACGCCGRequestPayload: Payload for Cyclocartography time-series calculations. - `bodies` string[]: Explicit body name selection. Supported: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, MeanNode, SouthNode, TrueNode, TrueSouthNode, MeanLilith, OscuLilith, Vertex, and the seven Hermetic lots Fortune, Spirit, Eros, Necessity, Courage, Victory and Nemesis. The eight Uranian (Hamburg School) hypothetical points (Cupido, Hades, Zeus, Kronos, Apollon, Admetos, Vulkanus, Poseidon) are accepted too, but only when named here: they are opt-in and never appear in a group's default roster. A lot named here resolves only under `group: "hermetic"` or `group: "all"` (this endpoint defaults to `all`); naming one under another group, or below the Scale tier, is rejected with 422 rather than silently returning the whole roster. Aliases: NorthNode/Rahu/Node -> MeanNode; TrueNorthNode/TrueRahu -> TrueNode; Ketu -> SouthNode; Vulcanus -> Vulkanus. The extended catalog is accepted too, by name and only when named: the sb441 main-belt asteroids (Hygiea, Eunomia, Psyche, Europa (asteroid), Cybele, Sylvia, Thisbe, Camilla, Iris, Davida, Euphrosyne, Interamnia), the trans-Neptunian objects (Eris, Sedna, Makemake, Haumea, Quaoar, Orcus, Ixion, Varuna, Chaos, Gonggong, Salacia), the extra centaurs (Asbolus, Hylonome, Nessus, Chariklo) and about forty further asteroids (Eros (asteroid), Sappho, Lilith (asteroid), Fortuna, Pandora, Diana, Hekate and more) - GET /catalogs/bodies lists them all. The asteroid Eros is `Eros (asteroid)`: plain `Eros` is the Hermetic lot. Each extended body named adds 1 credit to the request (capped at +20); the standard roster, the Uranian set and the lots are covered by the base price. Extended bodies are never in a group's default roster. - `custom_bodies` ACGCustomBody[], nullable: Enterprise tier. Caller-supplied fixed points drawn like bodies: each `{id, name?, longitude/latitude or ra_deg/dec_deg, metadata?}` yields MC/IC/AC/DC lines (and aspect lines) at the coordinates given, with `id` and `metadata` echoed back. TOP-LEVEL field, a sibling of `bodies`. Up to 32 points, 1 credit each (with extended catalog bodies, capped at +20 per request). See the ACGCustomBody schema. Below Enterprise the request is refused with 403. - `dec_deg` number, double, nullable: Declination in degrees, -90 to 90. Equatorial frame: give with `ra_deg`. - `id` string, required: Your identifier for this point: 1-64 characters, letters, digits and `_ . : -`, starting with a letter or digit. Unique within the request (case-insensitive). Echoed as `custom_id`. - `latitude` number, double, nullable: Ecliptic latitude in degrees, -90 to 90. Optional, default 0. Ecliptic frame only. - `longitude` number, double, nullable: Ecliptic longitude in degrees, any real value (wrapped into [0, 360)). Ecliptic frame: give this and, optionally, `latitude`. - `metadata` object, nullable: Arbitrary JSON object, echoed back verbatim on every line and in `metadata.bodies`. At most 2048 bytes serialized. Never interpreted. - `name` string, nullable: Display label and `body_name` for this point. Defaults to `id`. Up to 64 characters. - `ra_deg` number, double, nullable: Right ascension in DEGREES (0-360, wrapped), not hours. Equatorial frame: give with `dec_deg`. - `end_epoch` string, required: End of analysis window (ISO-8601). A clock time must carry its own zone ('Z' or ±HH:MM); a zone-less clock time is rejected with 400 ambiguous_datetime. A date-only value resolves to 12:00 UTC. - `epoch` string, required: ISO-8601 datetime of the birth or event. Either put the zone on the value itself as a 'Z' or ±HH:MM suffix ("1987-07-15T09:01:00-05:00"), or send the naive local wall-clock time ("1987-07-15T09:01:00") and name its zone in the sibling `timezone` field. A zone-less clock time with no `timezone` is rejected with 400 ambiguous_datetime and is NEVER read as UTC. A date-only value resolves to 12:00 UTC. Note: `start_epoch`/`end_epoch` are analysis-window bounds, not birth data, and still require their own zone suffix. - `group` string, nullable: Body group selector. `all` (default here, unlike the other ACG endpoints) = planets + asteroids + the Hermetic lots; `standard` = planets + asteroids only; `hermetic` = the lots alone; `hd` = the Human Design 13. Narrow further with `bodies` — e.g. `bodies: ["Moon","Saturn"]` returns those two and nothing else. The lots are a Scale-tier feature: below Scale the `all` default (or an explicit `hermetic`/`all`) is downgraded to the standard roster, and naming a lot in `bodies` is rejected with 422. - `jd` number, double: Julian Day (alternative to epoch) - `lat` number: Analysis target latitude. Accepted alias of 'target_lat'; ignored when 'target_lat' is present. - `lon` number: Analysis target longitude. Accepted alias of 'target_lon'; ignored when 'target_lon' is present. - `mode` 'transit' | 'ccg_hybrid', nullable: Calculation mode. 'transit' (default): all bodies use live transiting positions. 'ccg_hybrid': inner planets (Sun, Moon, Mercury, Venus, Mars) and lunar nodes use secondary progressions from the natal epoch; outer planets (Jupiter+) remain transits. - `natal` ACGNatalRequest: Natal geographical data for ACG offset calculation. - `birthplace_alt_m` number - `birthplace_lat` number: Birthplace latitude. Both birthplace coordinates must be supplied together -- a natal object with an incomplete pair is rejected rather than defaulting to 0,0. Distinct from the analysis target coordinates on the enclosing payload. - `birthplace_lon` number: Birthplace longitude. Both birthplace coordinates must be supplied together -- a natal object with an incomplete pair is rejected rather than defaulting to 0,0. Distinct from the analysis target coordinates on the enclosing payload. - `houses_system` string - `options` ACGOptionsRequest: Configuration options for AstroCartography calculations. - `angle_epoch` string: Decouple the rotational frame from the position epoch: body positions come from epoch/jd as usual, but ACG line angles are projected against this epoch's GMST. Accepts an ISO-8601 UTC datetime or a bare Julian Day. Empty/omitted = angles use the position epoch (default, unchanged). Use to overlay a secondary chart on a base frame — e.g. Human Design Design-register lines on the natal map (positions at the Design epoch, angles at the natal epoch), matching the hd_expression heatmap convention; also progressed/return overlays. Positions and obliquity stay on the position epoch, so every line is rigidly translated in longitude by the GMST difference. - `aspect_angles` number[]: Angles to compute aspects for - `asteroid_groups` ACGAsteroidGroup[]: Filter by asteroid group. Main belt and fixed stars are explicitly prohibited. - `include_aspects` boolean: Include aspect lines - `include_hd_gate` boolean: Enrich every emitted line feature with the Human Design gate its body's ecliptic longitude carries (properties.hd_gate: gate/line/color/tone/base). Purely additive — does not change the body set or geometry. Default false. Combine with bodies:["Earth"] or group:"hd" for the HD-13 body set. - `include_hd_lot_gates` boolean: With include_hd_gate, also attach the Human Design gate to Hermetic Lot lines (Fortune, Spirit, and the rest of the lot suite), computed from the lot's own ecliptic longitude in the personality register. Lots are left out of HD enrichment by default; no effect without include_hd_gate. Purely additive. Default false. - `include_lines` boolean: CCG only: emit MC/IC/AC/DC GeoJSON line geometry per snapshot (identical to /acg/power-lines, with ccg_hybrid progression applied per body). Default false. No effect on /acg/natal-lines. - `include_midpoints` boolean: Include planetary midpoint lines - `include_parans` boolean: Include parans (latitude crossings) - `line_types` string[]: Line types to include. Supported: MC, IC, AC, DC, ASP. Aliases: POWER -> MC+IC+AC+DC; ASPECT/SPECT -> ASP. - `paran_lat_cutoff` number, double: Maximum absolute latitude (in degrees) for paran crossing points. Crossings whose intersection latitude exceeds this value (north or south) are excluded from the response. When null or omitted, no cutoff is applied (current behavior preserved). Range: 0-90. - `refraction_correction` boolean: Apply atmospheric refraction to AC/DC - `resolution` integer: Resolution slices for mapping - `scoring` 'natal_weighted', nullable: Scoring mode. Default (null/omitted): geographic proximity only in 'scores'. 'natal_weighted': adds a 'natal_scores' map to each snapshot showing how strongly each transiting body aspects natal chart positions (0-1 scale, based on conjunction/opposition/trine/square/sextile within standard orbs). - `start_epoch` string, required: Start of analysis window (ISO-8601). A clock time must carry its own zone ('Z' or ±HH:MM); a zone-less clock time is rejected with 400 ambiguous_datetime. A date-only value resolves to 12:00 UTC. - `step_days` number: Time step in days - `target_lat` number: Analysis target latitude. Canonical spelling; alias of 'lat'. Required as part of a complete coordinate pair -- a request with no complete pair is rejected rather than defaulting to 0,0. - `target_lon` number: Analysis target longitude. Canonical spelling; alias of 'lon'. Required as part of a complete coordinate pair -- a request with no complete pair is rejected rather than defaulting to 0,0. - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets. - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user. - `iana_name` string: IANA timezone name - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used. - `utc_offset` number: UTC offset in hours ## Response `200` Successful Response - object ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)