{"id":"finance/analogues","method":"POST","url":"https://astro-agent.dev/v1/finance/analogues","price_usd":"0.25","tier":"premium","title":"Sky analogues (matching skies)","summary":"Find the past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance.","description":"Matching skies by geometry, data only: give a reference (a UTC moment, 'now', your own positions, or a birth sky: compare a birth sky to past/future dates — 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.","input_schema":{"type":"object","properties":{"reference":{"description":"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 birth sky {birth: {datetime: local '1990-05-15T14:30', latitude, longitude, timezone?}} to compare a birth sky to past/future dates. The birth 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).","oneOf":[{"type":"string"},{"type":"object","properties":{"datetime":{"type":"string"}},"required":["datetime"]},{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":["number","boolean"]}},"datetime":{"type":"string"}},"required":["values"]},{"type":"object","properties":{"birth":{"type":"object","properties":{"datetime":{"type":"string","description":"Local birth time, e.g. '1990-05-15T14:30', or the date alone if the time is unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone":{"type":"string","description":"IANA zone, e.g. 'Europe/Paris'; optional with latitude/longitude or an offset in datetime."}},"required":["datetime"]}},"required":["birth"]}],"examples":["2026-10-29T00:00Z",{"birth":{"datetime":"1990-05-15T14:30","latitude":48.8566,"longitude":2.3522}}]},"direction":{"type":"string","enum":["past","future","both"],"default":"both","description":"Search before the reference (a birth: before the birth moment), after it, or both (default; the only choice with reference.values without 'datetime')."},"range":{"type":"object","properties":{"start":{"type":"string","description":"First UTC date, YYYY-MM-DD, 1800..2199."},"end":{"type":"string","description":"Last UTC date, YYYY-MM-DD (inclusive)."}},"description":"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')."},"resolution":{"type":"string","enum":["1h","4h","12h","1d","1w"],"default":"1d","description":"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":{"type":"string","enum":["geocentric","heliocentric","both"],"default":"geocentric","description":"Positions seen from the Earth, from the Sun, or both."},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","earth","mars","jupiter","saturn","uranus","neptune","pluto"]},"description":"Bodies to match. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio)."},"features":{"type":"array","items":{"type":"string","enum":["longitude","aspects","declination","retrograde"]},"description":"What to compare: 'longitude' (default), 'aspects' (the angle between every pair of bodies), 'declination', 'retrograde' (geocentric flags, Mercury..Pluto)."},"weights":{"type":"object","additionalProperties":{"type":"number","minimum":0},"description":"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":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"How many matches."},"max_distance":{"type":"number","minimum":0,"maximum":180,"description":"Optional: only matches whose score (degrees) is at most this."},"min_separation_days":{"type":"number","minimum":0,"default":30,"description":"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":{"type":"boolean","default":false,"description":"Keep only dates whose retrograde flags equal the reference's."},"format":{"type":"string","enum":["columns","rows"],"default":"columns","description":"'columns' (pandas.DataFrame(result['matches'])) or 'rows' (one object per match)."},"options":{"type":"object","description":"Optional zodiac settings.","properties":{"zodiac":{"type":"string","enum":["tropical","sidereal"],"default":"tropical","description":"'tropical' (default) or 'sidereal' (pair it with 'ayanamsa')."},"ayanamsa":{"type":"string","enum":["fagan_bradley","krishnamurti","lahiri","raman","true_chitrapaksha","yukteshwar"],"default":"lahiri","description":"Only with zodiac=sidereal."}}}}},"example_request":{"reference":"2026-10-29T00:00Z","direction":"past","bodies":["jupiter","saturn","uranus","neptune","pluto"],"min_separation_days":3650,"top_n":5},"example_response":{"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.7.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."},"example_note":"real output of engine 1.7.0; lists shortened to 3 items"},"payment":"x402 or MPP; always paid. POST without payment to receive the 402 challenge.","catalog":"https://astro-agent.dev/v1/catalog"}