# AI Ephemeris Data

AI Ephemeris Data is a static ephemeris archive for AI agents and tools that
need documented planetary positions without calling a live calculation API.

Start here:

- Dataset catalog:
  https://raw.githubusercontent.com/ephemeris-ai/ai-ephemeris-data/main/catalog.json

- Human and AI usage guide:
  https://github.com/ephemeris-ai/ai-ephemeris-data/blob/main/AI_USAGE.md

- JSON schema:
  https://raw.githubusercontent.com/ephemeris-ai/ai-ephemeris-data/main/schema.json

- Project page:
  https://ephemeris-ai.github.io/ai-ephemeris-data/

- Related live astrology tools:
  https://app.on-lineastrology.com/

Lookup rule for AI agents:

1. Read catalog.json first.
2. Choose a dataset covering the requested UTC date and cadence.
3. Read that dataset's index.json.
4. Follow the dataset storage rule. Example datasets may expose a daily
   .jsonl.gz file directly; generated ranges may use monthly ZIP archives.
5. For monthly ZIP datasets, read monthly_index.json, download the matching
   month archive, then open the requested daily .jsonl.gz file inside it.
6. Use nearest-row lookup or interpolation, and say which method was used.

For a match or timed event:

- Convert local civil time to UTC first.
- Prefer the 10min layer when available.
- Read the daily file for the UTC date, either directly or from the matching
  monthly ZIP archive.
- Use one row for the scheduled start, or several rows for a realistic event window.
- If the requested day is not listed in the dataset index, say the archive does
  not currently contain that date/cadence.

Default coordinate model:

- UTC timestamps
- Julian Day UT
- geocentric apparent tropical ecliptic longitude and latitude
- degrees normalized to 0 <= longitude < 360
- no houses, no Ascendant, no MC, no location-specific values

Body codes:

So Mo Me Ve Ma Ju Sa Ur Ne Pl Nn Nt Ll Lt Ch Ph Ce Pa Jo Va Wa Se

Important:

- Do not guess planetary positions when a matching static file exists.
- Do not treat local civil time as UTC.
- Do not calculate houses from this dataset.
- Do not claim that aspect-event files or match-window helper files exist until
  they are listed in catalog.json.
- The main branch contains examples only; full ranges are listed in catalog.json
  when available and are distributed outside the default branch.
- In ranges generated before 2026-07-10, distance_au of Nn, Nt, Lt is 0.0 and
  Ll is the constant 0.002712 (placeholder values); treat lunar-point
  distance_au as informational only. See data_revision_notes in catalog.json.