{
  "schema_version": "1.0",
  "project": "ai-ephemeris-data",
  "purpose": "AI-readable static ephemeris dataset catalog",
  "lookup_rule": "Read this catalog first, choose the dataset covering the requested UTC date and cadence, then follow that dataset storage rule. Example files may be direct daily JSONL/GZIP files; generated ranges may use monthly ZIP archives containing daily JSONL/GZIP files.",
  "coordinate_model": {
    "time_scale": "UTC input, Julian Day UT output",
    "frame": "geocentric",
    "zodiac": "tropical",
    "coordinates": "ecliptic",
    "longitude_unit": "degrees",
    "position_type": "apparent",
    "ayanamsa": null,
    "location_dependent_values": false
  },
  "recommended_cadence_policy": [
    {
      "cadence": "10min",
      "status": "primary AI lookup layer",
      "use": "ordinary chart-position lookup and match start windows"
    },
    {
      "cadence": "1min",
      "status": "planned optional high-resolution layer",
      "use": "exact-time match windows and final checks"
    }
  ],
  "planned_extensions": [
    "daily aspect event files",
    "match-window helper examples",
    "larger generated historical ranges outside the default branch"
  ],
  "data_revision_notes": [
    {
      "date": "2026-07-10",
      "id": "runtime-0.1.3-distance-fix",
      "applies_to": "all 10min ranges generated before 2026-07-10",
      "note": "Files were generated with runtime <= swetest-php-0.1.2-preview. In those files distance_au of the lunar points is a placeholder: Nn, Nt, Lt have distance_au = 0.0 and Ll has the constant 0.002712. Runtime 0.1.3-preview (audited against the Swiss Ephemeris 2.10.03 C sources and verified against the official swetest binary) returns real distances for these points. Longitudes, latitudes, speeds, signs, and retrograde flags agree within 0.0005 arcsec and are unaffected. The published ranges are intentionally not regenerated; treat lunar-point distance_au as informational only."
    }
  ],
  "datasets": [
    {
      "id": "10min-1950-1999",
      "status": "generated",
      "description": "Generated 10-minute ephemeris dataset for 1950-01-01 through 1999-12-31 UTC, stored as monthly ZIP archives.",
      "repository": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data",
      "index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-1950-1999/index.json",
      "monthly_index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-1950-1999/monthly_index.json",
      "base_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/",
      "storage": "monthly_zip_archives",
      "date_range": {
        "start": "1950-01-01",
        "end": "1999-12-31"
      },
      "cadences": [
        {
          "cadence": "10min",
          "date_range": {
            "start": "1950-01-01",
            "end": "1999-12-31"
          },
          "recommended_use": "primary AI lookup layer for ordinary chart-position use and match starts"
        }
      ]
    },
    {
      "id": "10min-2000-2019",
      "status": "generated",
      "repository": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data",
      "storage": "monthly_zip_archives",
      "index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-2000-2019/index.json",
      "monthly_index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-2000-2019/monthly_index.json",
      "base_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/",
      "date_range": {
        "start": "2000-01-01",
        "end": "2019-12-31"
      },
      "cadences": [
        {
          "cadence": "10min",
          "date_range": {
            "start": "2000-01-01",
            "end": "2019-12-31"
          },
          "recommended_use": "primary AI lookup layer for ordinary chart-position use and match starts"
        }
      ]
    },
    {
      "id": "10min-2020-2030",
      "status": "generated",
      "description": "Generated 10-minute ephemeris dataset for 2020-01-01 through 2030-12-31 UTC, stored on Hugging Face as monthly ZIP archives.",
      "repository": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data",
      "storage": "monthly_zip_archives",
      "index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-2020-2030/index.json",
      "monthly_index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-2020-2030/monthly_index.json",
      "base_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/",
      "date_range": {
        "start": "2020-01-01",
        "end": "2030-12-31"
      },
      "cadences": [
        {
          "cadence": "10min",
          "date_range": {
            "start": "2020-01-01",
            "end": "2030-12-31"
          },
          "recommended_use": "primary AI lookup layer for ordinary chart-position use and match starts",
          "lookup_rule": "Open monthly_index.json, download the matching monthly ZIP, then read the requested YYYY-MM-DD.jsonl.gz file inside it."
        }
      ],
      "mirror_note": "An earlier GitHub data branch may exist as a legacy mirror, but Hugging Face is the preferred data endpoint for generated ranges."
    },
    {
      "id": "10min-2031-2050",
      "status": "generated",
      "description": "Generated 10-minute ephemeris dataset for 2031-01-01 through 2050-12-31 UTC, stored as monthly ZIP archives.",
      "repository": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data",
      "index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-2031-2050/index.json",
      "monthly_index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-2031-2050/monthly_index.json",
      "base_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/",
      "storage": "monthly_zip_archives",
      "date_range": {
        "start": "2031-01-01",
        "end": "2050-12-31"
      },
      "cadences": [
        {
          "cadence": "10min",
          "date_range": {
            "start": "2031-01-01",
            "end": "2050-12-31"
          },
          "recommended_use": "primary AI lookup layer for ordinary chart-position use and match starts"
        }
      ]
    },
    {
      "id": "examples-main",
      "status": "examples",
      "description": "Small default-branch example dataset for the primary 10-minute lookup layer. Full generated ranges are listed as separate catalog entries when available.",
      "repository": "https://github.com/ephemeris-ai/ai-ephemeris-data",
      "index_url": "https://raw.githubusercontent.com/ephemeris-ai/ai-ephemeris-data/main/index.json",
      "pages_index_url": "https://ephemeris-ai.github.io/ai-ephemeris-data/index.json",
      "base_url": "https://raw.githubusercontent.com/ephemeris-ai/ai-ephemeris-data/main/",
      "date_range": {
        "start": "2026-01-01",
        "end": "2026-01-01"
      },
      "cadences": [
        {
          "cadence": "10min",
          "date_range": {
            "start": "2026-01-01",
            "end": "2026-01-01"
          },
          "recommended_use": "single-day example file"
        }
      ]
    },
    {
      "id": "10min-1900-1949",
      "status": "generated",
      "description": "Generated 10-minute ephemeris dataset for 1900-01-01 through 1949-12-31 UTC, stored as monthly ZIP archives.",
      "repository": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data",
      "index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-1900-1949/index.json",
      "monthly_index_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/datasets/10min-1900-1949/monthly_index.json",
      "base_url": "https://huggingface.co/datasets/ephemeris-ai/ai-ephemeris-data/raw/main/",
      "storage": "monthly_zip_archives",
      "date_range": {
        "start": "1900-01-01",
        "end": "1949-12-31"
      },
      "cadences": [
        {
          "cadence": "10min",
          "date_range": {
            "start": "1900-01-01",
            "end": "1949-12-31"
          },
          "recommended_use": "primary AI lookup layer for ordinary chart-position use and match starts"
        }
      ]
    }
  ],
  "large_dataset_policy": "Full generated ranges are published outside the default branch. The preferred public data channel is the Hugging Face dataset using monthly ZIP archives to avoid thousands of tiny LFS objects."
}