Docs › Sky similarity search (matching skies)

Sky similarity search (matching skies)

The past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance.

POST https://astro-agent.dev/v1/astronomy/sky-analogues · $0.25 per call · MCP tool similar_skies · Try it in the playground

Searches a date grid (1 hour to 1 week steps, 1800-2200) for the skies closest to a reference: by longitude, by the separations between bodies, by declination, optionally with the same retrograde flags. The score is a weighted mean angular distance in degrees, defined in result.settings.metric. Data for your own analysis — never a signal or forecast.

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (1,000 calls a month, up to 100 of them on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.

Parameters

ParameterTypeRequiredDefaultDescription
referencevalueThe sky to match: 'now' (default; the current UTC hour or day, echoed in result.reference.date_utc), a UTC moment ('2026-10-29T00:00Z' or 'YYYY-MM-DD'), {datetime: ...}, your own values {values: {feature id: value}} (add 'datetime' to anchor direction and range at a time), or a local date-time and place {place: {datetime: local '1990-05-15T14:30', latitude, longitude, timezone?}}: the time zone comes from the coordinates or 'timezone'; a date alone means 12:00 local with a TIME_UNKNOWN warning. meta.reference_resolution gives the equivalent {values, datetime} request. Feature ids: '<geo|helio>.<body>' (longitude, 0-360), '<geo|helio>.<a>-<b>:angle' (separation, 0-180), '<geo|helio>.<body>:declination' (degrees) and 'geo.<body>:retrograde'.
directionstring: past | future | both"both"Search before the reference (with a local date-time and place: before that moment), after it, or both (default; the only choice with reference.values without 'datetime').
rangeobjectCandidate dates. Default (a reference with a time): the longest window the caps allow, up to 100 years in the chosen direction (50 on each side for 'both').
range.startstringFirst UTC date, YYYY-MM-DD, 1800..2199.
range.endstringLast UTC date, YYYY-MM-DD (inclusive).
resolutionstring: 1h | 4h | 12h | 1d | 1w"1d"Step of the candidate grid. At most 36,600 candidate dates per call, and at most 660,000 dates x ephemeris series (one per body and perspective, plus one per retrograde-flagged body).
perspectivestring: geocentric | heliocentric | both"geocentric"Positions seen from the Earth, from the Sun, or both.
bodiesarray of string (sun, moon, mercury, venus, earth, mars, jupiter, saturn, uranus, neptune, pluto)Bodies to match. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio).
featuresarray of string (longitude, separations, declination, retrograde)What to compare: 'longitude' (default), 'separations' (the angle between every pair of bodies), 'declination', 'retrograde' (a filter on equal retrograde flags).
weightsobjectOptional {feature id: weight}, default 1 each, e.g. {'geo.jupiter': 2}. Feature ids: '<geo|helio>.<body>' (longitude, 0-360), '<geo|helio>.<a>-<b>:angle' (separation, 0-180), '<geo|helio>.<body>:declination' (degrees) and 'geo.<body>:retrograde' (true/false).
top_ninteger10How many matches.
max_distancenumberOptional: only matches whose score (degrees) is at most this.
min_separation_daysnumber30Minimum gap between two matches and between a match and the reference time, so one passage gives one match. Raise it (e.g. 3650) to skip the current cycle of slow planets.
require_same_retrogradebooleanfalseKeep only dates whose retrograde flags equal the reference's.
formatstring: columns | rows"columns"'columns' (pandas.DataFrame(result['matches'])) or 'rows' (one object per match).

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/sky-analogues \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference": "2026-10-29T00:00Z", "direction": "past", "bodies": ["jupiter", "saturn", "uranus", "neptune", "pluto"], "top_n": 5, "min_separation_days": 3650}'

Python

import os
import requests

body = {'reference': '2026-10-29T00:00Z',
 'direction': 'past',
 'bodies': ['jupiter', 'saturn', 'uranus', 'neptune', 'pluto'],
 'top_n': 5,
 'min_separation_days': 3650}
r = requests.post("https://astro-agent.dev/v1/astronomy/sky-analogues", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

m = data["result"]["matches"]
for date, score in zip(m["date_utc"], m["score"]):
    print(date, f"distance {score:.3f} deg")
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"reference": "2026-10-29T00:00Z", "direction": "past", "bodies": ["jupiter", "saturn", "uranus", "neptune", "pluto"], "top_n": 5, "min_separation_days": 3650};
const res = await fetch("https://astro-agent.dev/v1/astronomy/sky-analogues", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

const m = data.result.matches;
m.date_utc.forEach((d, i) => console.log(d, "distance", m.score[i].toFixed(3), "deg"));
console.log("result_sha256:", data.meta.result_sha256);

Example response

A real response to the request above (lists shortened to 3 items). The same request always returns this result_sha256:

f3f06a3f5f188ab0819361f443f2c669855bcb66f908f1220526c49ba43c382c

{
  "endpoint": "astronomy/sky-analogues",
  "result": {
    "settings": {
      "reference_source": "datetime",
      "direction": "past",
      "range": {
        "start": "1926-10-29T00:00Z",
        "end": "2026-10-28T00:00Z",
        "default": true
      },
      "resolution": "1d",
      "perspectives": [
        "geocentric"
      ],
      "bodies": {
        "geocentric": [
          "jupiter",
          "saturn",
          "uranus"
        ]
      },
      "features": [
        "longitude"
      ],
      "feature_ids": [
        "geo.jupiter",
        "geo.saturn",
        "geo.uranus"
      ],
      "weights": {
        "geo.jupiter": 1.0,
        "geo.saturn": 1.0,
        "geo.uranus": 1.0,
        "geo.neptune": 1.0,
        "geo.pluto": 1.0
      },
      "top_n": 5,
      "max_distance": null,
      "min_separation_days": 3650.0,
      "require_same_retrograde": false,
      "format": "columns",
      "metric": {
        "score": "score = sum(w_i * d_i) / sum(w_i) over the matched features i, in degrees; 0 = the same sky",
        "circular_difference": "circ(a, b) = |((a - b + 180) mod 360) - 180|, in [0, 180] (mod with a non-negative result)",
        "longitude": "feature '<geo|helio>.<body>': d = circ(longitude_reference, longitude_candidate)",
        "declination": "feature '<geo|helio>.<body>:declination': d = |declination_reference - declination_candidate| (degrees, not folded)",
        "retrograde": "feature 'geo.<body>:retrograde' (retrograde = geocentric longitude speed < 0): d = 0 if the flag equals the reference's, else 180",
        "weights": "w_i = 1 unless 'weights' {feature id: w >= 0} says otherwise",
        "selection": "eligible candidates (direction; at least min_separation_days from the reference time; score <= max_distance; the reference's retrograde flags if require_same_retrograde) are ordered by (score rounded to 1e-9, timestamp), and each is kept if it lies at least min_separation_days from every match already kept, until top_n are kept",
        "values": "positions on the candidate grid from DE440 via Skyfield with IAU 2000B nutation, as in the planetary-lines series; the score is computed before the response rounds values to 1e-6",
        "separations": "feature '<geo|helio>.<a>-<b>:angle': angle = circ(longitude_a, longitude_b), in [0, 180]; d = |angle_reference - angle_candidate|"
      },
      "frames": {
        "geocentric": "geocentric apparent, true ecliptic and equinox of date; declinations on the true equator of date",
        "heliocentric": "heliocentric geometric positions (Sun -> body, no light-time), true ecliptic and equinox of date"
      },
      "columns": "rank, date_utc, timestamp (unix s), days_from_reference, score (degrees), each body's longitude '<geo|helio>.<body>', 'geo.<body>:retrograde', the matched angle and declination values, and 'distance:<feature id>' (degrees)",
      "note": "Matching skies by a stated angular distance. Data for your own analysis — never a signal or forecast.",
      "longitude_reference": "ecliptic longitude from the true equinox of date (0-360 degrees)"
    },
    "reference": {
      "source": "datetime",
      "date_utc": "2026-10-29T00:00Z",
      "timestamp": 1793232000,
      "geo.jupiter": 143.948196,
      "geo.saturn": 9.479918,
      "geo.uranus": 64.782886,
      "geo.neptune": 2.148338,
      "geo.pluto": 303.107915,
      "geo.jupiter:retrograde": false,
      "geo.saturn:retrograde": true,
      "geo.uranus:retrograde": true,
      "geo.neptune:retrograde": true,
      "geo.pluto:retrograde": false
    },
    "matches": {
      "rank": [
        1,
        2,
        3
      ],
      "date_utc": [
        "2016-05-09T00:00Z",
        "2003-02-17T00:00Z",
        "1992-05-01T00:00Z"
      ],
      "timestamp": [
        1462752000,
        1045440000,
        704678400
      ],
      "days_from_reference": [
        -3825.0,
        -8655.0,
        -12599.0
      ],
      "score": [
        42.558526,
        55.155907,
        68.708539
      ],
      "geo.jupiter": [
        163.255656,
        131.204484,
        154.631866
      ],
      "geo.saturn": [
        254.888979,
        82.161893,
        317.872687
      ],
      "geo.uranus": [
        22.071004,
        328.75559,
        287.981601
      ],
      "geo.neptune": [
        341.692814,
        311.30311,
        288.927464
      ],
      "geo.pluto": [
        287.381092,
        259.626592,
        231.87828
      ],
      "geo.jupiter:retrograde": [
        true,
        true,
        false
      ],
      "geo.saturn:retrograde": [
        true,
        true,
        false
      ],
      "geo.uranus:retrograde": [
        false,
        false,
        true
      ],
      "geo.neptune:retrograde": [
        false,
        false,
        true
      ],
      "geo.pluto:retrograde": [
        true,
        false,
        true
      ],
      "distance:geo.jupiter": [
        19.30746,
        12.743712,
        10.68367
      ],
      "distance:geo.saturn": [
        114.59094,
        72.681975,
        51.607231
      ],
      "distance:geo.uranus": [
        42.711882,
        96.027297,
        136.801286
      ],
      "distance:geo.neptune": [
        20.455525,
        50.845228,
        73.220874
      ],
      "distance:geo.pluto": [
        15.726823,
        43.481323,
        71.229635
      ]
    },
    "counts": {
      "candidates": 36525,
      "eligible": 32876,
      "matches": 5
    }
  },
  "meta": {
    "engine": "astro-agents/1.10.0",
    "ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
    "astronomy_library": "skyfield/1.55",
    "frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
    "deterministic": true,
    "llm_used": false,
    "input_sha256": "5ba877105c599daecf92c2eccb7ca7b80fd6fdc38abb2efd37d4464dfb573988",
    "result_sha256": "f3f06a3f5f188ab0819361f443f2c669855bcb66f908f1220526c49ba43c382c",
    "reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash.",
    "metric": {
      "score": "score = sum(w_i * d_i) / sum(w_i) over the matched features i, in degrees; 0 = the same sky",
      "circular_difference": "circ(a, b) = |((a - b + 180) mod 360) - 180|, in [0, 180] (mod with a non-negative result)",
      "longitude": "feature '<geo|helio>.<body>': d = circ(longitude_reference, longitude_candidate)",
      "declination": "feature '<geo|helio>.<body>:declination': d = |declination_reference - declination_candidate| (degrees, not folded)",
      "retrograde": "feature 'geo.<body>:retrograde' (retrograde = geocentric longitude speed < 0): d = 0 if the flag equals the reference's, else 180",
      "weights": "w_i = 1 unless 'weights' {feature id: w >= 0} says otherwise",
      "selection": "eligible candidates (direction; at least min_separation_days from the reference time; score <= max_distance; the reference's retrograde flags if require_same_retrograde) are ordered by (score rounded to 1e-9, timestamp), and each is kept if it lies at least min_separation_days from every match already kept, until top_n are kept",
      "values": "positions on the candidate grid from DE440 via Skyfield with IAU 2000B nutation, as in the planetary-lines series; the score is computed before the response rounds values to 1e-6",
      "separations": "feature '<geo|helio>.<a>-<b>:angle': angle = circ(longitude_a, longitude_b), in [0, 180]; d = |angle_reference - angle_candidate|"
    },
    "disclaimer": "Data for your own analysis — never a signal or forecast."
  }
}

Response fields

FieldTypeDescription
result.settingsobjectSettings applied: reference source, direction, range, resolution, perspectives, bodies, features and their ids, weights, top_n, max_distance, min_separation_days, frames, column names and the metric definition (formula per feature).
result.referenceobjectThe reference sky: its date_utc and timestamp with every body's longitude and retrograde flag (and matched angles / declinations), or the values you gave.
result.matchesobject | arrayMatching dates ranked by score: 'columns' format = {rank: [...], date_utc: [...], timestamp: [...], score: [...], <body or feature>: [...], distance:<feature id>: [...]}; 'rows' format = one object per match.
result.countsobjectNumber of candidate dates, eligible dates and matches.
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine release and ephemeris (NASA/JPL DE440).

CSV

Add ?format=csv to get the table of the result as CSV (gzip when your client sends Accept-Encoding: gzip): POST https://astro-agent.dev/v1/astronomy/sky-analogues?format=csv. Same price and quota as JSON; the X-Result-SHA256 header is the hash of the JSON result the CSV is a view of. Long ranges in one file: bulk export.

Errors

400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.