ACG

Cyclocartography Time-Series (Go Engine)

Compute cyclocartography transit snapshots over a time window.

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

Request body

bodiesstring[]

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.

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

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

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

jdnumber double

Julian Day (alternative to epoch)

latnumber

Analysis target latitude. Accepted alias of 'target_lat'; ignored when 'target_lat' is present.

lonnumber

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.

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_epochstring 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_daysnumber

Time step in days

target_latnumber

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_lonnumber

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.

Example request

{
  "end_epoch": "2026-12-31T00:00:00Z",
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  },
  "start_epoch": "2026-01-01T00:00:00Z"
}

Response

Successful Response

object required

Changes

No recorded changes to this operation across all 1 revision of this API.