Docs › Planetary longitude series (geocentric + heliocentric)
Planetary longitude series (geocentric + heliocentric)
Planetary longitudes (geocentric and heliocentric) at a moment or as a longitude time series at chosen intervals, with angular offsets and multi-body averages.
POST https://astro-agent.dev/v1/finance/planetary-lines · $0.20 per call · MCP tool planetary_lines
· Try it in the playground
Planetary longitude time series, data only: the longitude of each planet, seen from the Earth and from the Sun in one call, plus the angular offsets you ask for (+/-90, 120...), multi-body longitude averages (Jupiter..Pluto, Mercury..Pluto), speeds, retrograde flags and declinations. Snapshot ('datetime') or series ('start', 'end', 'interval' 1h..1w, up to 1000 samples, optionally unwrapped for plotting) in columns ready for pandas. With 'price_unit' (a scale factor) and 'price_range': the linear projection of each longitude onto a value scale, (degree + 360 k) x unit for every cycle k. Each result is hashed, so it can be cited and replayed.
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 |
|---|---|---|---|---|
datetime | string | | A moment (snapshot): ISO 8601 with Z or an offset, e.g. '2024-01-01T00:00Z'. A local time needs 'timezone' or coordinates. Omit when giving start/end. | |
timezone | string | | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. | |
start | string | | Series: first UTC date, YYYY-MM-DD. Example: '2024-01-01'. | |
end | string | | Series: last UTC date, YYYY-MM-DD (at most 1000 samples). | |
interval | string: 1h | 4h | 12h | 1d | 1w | "1d" | Series sampling step, in candle-timeframe notation. | |
time_utc | string | "00:00" | Series: UTC time of day of the first sample, HH:MM. | |
perspective | string: geocentric | heliocentric | both | "both" | Geocentric, heliocentric, or both in one call (default). | |
bodies | array of string (sun, moon, mercury, venus, earth, mars, jupiter, saturn, uranus, neptune, pluto, mean_node, true_node) | | Bodies to draw. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio). | |
aspects | value | | Aspect offsets added to every line (+angle and -angle). Default: the planet's own line only (conjunction). | |
averages | array of string (mean_of_5, circle_of_8) | | Multi-body longitude averages: mean_of_5 = (Jupiter+Saturn+Uranus+Neptune+Pluto)/5, circle_of_8 = (Mercury+Venus+Mars+Jupiter+Saturn+Uranus+Neptune+Pluto)/8, in each perspective. | |
average_method | string: arithmetic | circular | "arithmetic" | 'arithmetic' mean of the 0-360 longitude values or 'circular' (vector) mean of the directions. | |
price_unit | number | | Scale factor (value units per degree) for a linear projection of each longitude onto a value scale. With price_range: levels = (degree + 360 k) x price_unit, one per full 360-degree cycle k. | |
price_range | object | | The window of the value scale in which to list the projected levels, e.g. {min: 30000, max: 80000}. | |
price_range.min | number | | Lowest value on the scale to list. | |
price_range.max | number | | Highest value on the scale to list. | |
unwrap | boolean | false | Series: continuous degrees (no 360 -> 0 jump), for plotting lines across a chart. | |
include_declination | boolean | false | Series: also a declination column per body. | |
format | string: columns | rows | "columns" | Series layout: 'columns' (pandas.DataFrame(result['series'])) or 'rows' (one object per sample). | |
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/planetary-lines \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"start": "2024-01-01", "end": "2024-12-31", "interval": "1w", "bodies": ["jupiter", "saturn"], "perspective": "geocentric"}'Python
import os
import requests
body = {'start': '2024-01-01',
'end': '2024-12-31',
'interval': '1w',
'bodies': ['jupiter', 'saturn'],
'perspective': 'geocentric'}
r = requests.post("https://astro-agent.dev/v1/finance/planetary-lines", 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()
s = data["result"]["series"] # columns: time_utc, timestamp, geo.jupiter, geo.saturn
for t, jup, sat in list(zip(s["time_utc"], s["geo.jupiter"], s["geo.saturn"]))[:5]:
print(t, f"Jupiter {jup:8.3f} Saturn {sat:8.3f}")
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 = {"start": "2024-01-01", "end": "2024-12-31", "interval": "1w", "bodies": ["jupiter", "saturn"], "perspective": "geocentric"};
const res = await fetch("https://astro-agent.dev/v1/finance/planetary-lines", {
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 s = data.result.series; // columns: time_utc, timestamp, geo.jupiter, geo.saturn
s.time_utc.slice(0, 5).forEach((t, i) =>
console.log(t, "Jupiter", s["geo.jupiter"][i].toFixed(3), "Saturn", s["geo.saturn"][i].toFixed(3)));
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:
0de210ecc491abc1f71609970a621259808ba8e09341e656ba246fb146e08075
{
"endpoint": "finance/planetary-lines",
"result": {
"settings": {
"perspectives": [
"geocentric"
],
"zodiac": "tropical",
"bodies": {
"geocentric": [
"jupiter",
"saturn"
]
},
"aspects": [
"conjunction"
],
"line_offsets_deg": [
0.0
],
"averages": {},
"average_method": null,
"frames": {
"geocentric": "geocentric apparent, true ecliptic and equinox of date",
"heliocentric": "heliocentric geometric positions (Sun -> body, no light-time), true ecliptic and equinox of date"
},
"line_id": "<geo|helio>.<body or average>[+<offset deg>]; degree = (longitude + offset) mod 360",
"price_formula": "price = (degree + 360 k) x price_unit, for every integer k in price_range",
"interval": "1w",
"samples": 53,
"unwrap": false,
"format": "columns",
"columns": [
"geo.jupiter",
"geo.saturn"
],
"unwrapped": null
},
"series": {
"time_utc": [
"2024-01-01T00:00Z",
"2024-01-08T00:00Z",
"2024-01-15T00:00Z"
],
"timestamp": [
1704067200,
1704672000,
1705276800
],
"geo.jupiter": [
35.582393,
35.688617,
35.962617
],
"geo.saturn": [
333.243555,
333.889731,
334.585823
]
},
"counts": {
"samples": 53,
"columns": 2
}
},
"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": "cbe48fb4ed2b1df4a0b948d4e0a6d746d7cb6cb9b1fc5d5e4c5b2cbe62ab2390",
"result_sha256": "0de210ecc491abc1f71609970a621259808ba8e09341e656ba246fb146e08075",
"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."
}
}
Response fields
| Field | Type | Description |
|---|---|---|
result.settings | object | Settings applied: perspectives, zodiac, bodies, aspect offsets, averages and their members, frames, line id format, the value-scale projection formula (price_formula) and, for a series, interval, samples and columns. |
result.subject | object | Snapshot only: the resolved moment (UTC, Julian days, Delta T). |
result.lines | array | Snapshot only: one entry per line (id such as 'helio.jupiter+90', perspective, base body or average, offset, degree 0-360, position in sign; speed, retrograde flag and declination on base lines; projected value-scale levels when price_unit is given). |
result.price_levels | array | Snapshot with price_unit: every projected value-scale level inside price_range, sorted, with its line id. |
result.series | object | array | Series only: 'columns' format = {time_utc: [...], timestamp: [...], <line id>: [...]}; 'rows' format = one object per sample. |
result.counts | object | Number of lines and projected levels (snapshot) or of samples and columns (series). |
result.warnings | array | Notes on the input or the calculation (for example an assumed local noon when only a date is given). Present only when there is something to say. |
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.