Docs › Sky similarity search (matching skies)
Sky similarity search (matching skies)
Find 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/finance/analogues · $0.25 per call · MCP tool sky_analogues
· Try it in the playground
Matching skies by geometry, data only: give a reference (a UTC moment, 'now', your own positions, or a the sky at a local date-time and place — data only) and get the dates in a range (past, future or both, 1800-2200, 1h..1w grid) whose sky is closest, ranked by a weighted mean of circular longitude differences (geocentric and/or heliocentric), pair angles (aspects), declination differences and retrograde-flag mismatches, in degrees. Each match gives its date, unix timestamp, score, every body's exact longitude and retrograde flag and each feature's distance, in columns ready for pandas. The metric formula is in the response; the same request returns the same bytes and hash, future dates included. Up to 100 matches and 36,600 candidate dates per call; no market data. 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 (10,000 calls a month on the core routes, 100 a month 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 configuration {values: {feature id: value}} (add 'datetime' to anchor direction and range at a time), or a local date-time and place {birth: {datetime: local '1990-05-15T14:30', latitude, longitude, timezone?}} to compare the sky at that moment and place to past/future dates. That local moment is resolved as in /v1/western/positions (time zone from the coordinates or 'timezone'); a date alone means 12:00 local with a TIME_UNKNOWN warning (the Moon is then approximate, Jupiter..Pluto stay reliable). No houses or ascendant. meta.reference_resolution gives the equivalent {values, datetime} request, which returns the same result and result_sha256. 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). | |
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, aspects, declination, retrograde) | | What to compare: 'longitude' (default), 'aspects' (the angle between every pair of bodies), 'declination', 'retrograde' (geocentric flags, Mercury..Pluto). | |
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). | |
options | object | | Optional zodiac settings. | |
options.zodiac | string: tropical | sidereal | "tropical" | 'tropical' (default) or 'sidereal' (pair it with 'ayanamsa'). | |
options.ayanamsa | string: fagan_bradley | krishnamurti | lahiri | raman | true_chitrapaksha | yukteshwar | "lahiri" | Only with zodiac=sidereal. |
Example request
curl
curl -s https://astro-agent.dev/v1/finance/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"], "min_separation_days": 3650, "top_n": 5}'Python
import os
import requests
body = {'reference': '2026-10-29T00:00Z',
'direction': 'past',
'bodies': ['jupiter', 'saturn', 'uranus', 'neptune', 'pluto'],
'min_separation_days': 3650,
'top_n': 5}
r = requests.post("https://astro-agent.dev/v1/finance/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"], "min_separation_days": 3650, "top_n": 5};
const res = await fetch("https://astro-agent.dev/v1/finance/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:
b43da7c67d8a81c7d909d53815ef4f2c0ed3f4c9ec4206fc1daf988cf848ecb0
{
"endpoint": "finance/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,
"zodiac": "tropical",
"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)",
"aspects": "feature '<geo|helio>.<a>-<b>:angle': angle = circ(longitude_a, longitude_b), in [0, 180]; d = |angle_reference - angle_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"
},
"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, no market data. Data for your own analysis — never a signal or forecast."
},
"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.9.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": "db347636fc5618a75de1022d56a1ed2246014ee55f5375507ca2d01f9a22018a",
"result_sha256": "b43da7c67d8a81c7d909d53815ef4f2c0ed3f4c9ec4206fc1daf988cf848ecb0",
"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)",
"aspects": "feature '<geo|helio>.<a>-<b>:angle': angle = circ(longitude_a, longitude_b), in [0, 180]; d = |angle_reference - angle_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"
},
"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, zodiac, 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). |
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.