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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
reference | value | | The 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'. | |
direction | string: 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'). | |
range | object | | Candidate 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.start | string | | First UTC date, YYYY-MM-DD, 1800..2199. | |
range.end | string | | Last UTC date, YYYY-MM-DD (inclusive). | |
resolution | string: 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). | |
perspective | string: geocentric | heliocentric | both | "geocentric" | Positions seen from the Earth, from the Sun, or both. | |
bodies | array 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). | |
features | array 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). | |
weights | object | | Optional {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_n | integer | 10 | How many matches. | |
max_distance | number | | Optional: only matches whose score (degrees) is at most this. | |
min_separation_days | number | 30 | Minimum 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_retrograde | boolean | false | Keep only dates whose retrograde flags equal the reference's. | |
format | string: 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
| Field | Type | Description |
|---|---|---|
result.settings | object | Settings 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.reference | object | The 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.matches | object | array | Matching dates ranked by score: 'columns' format = {rank: [...], date_utc: [...], timestamp: [...], score: [...], <body or feature>: [...], distance:<feature id>: [...]}; 'rows' format = one object per match. |
result.counts | object | Number of candidate dates, eligible dates and matches. |
endpoint | string | The route that computed it. |
meta.input_sha256 | string | SHA-256 of the canonical request. |
meta.result_sha256 | string | SHA-256 of the canonical result: POST /v1/verify recomputes it. |
meta.engine_version / meta.ephemeris | string | Engine 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.