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

ParameterTypeRequiredDefaultDescription
datetimestringA 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.
timezonestringIANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date.
startstringSeries: first UTC date, YYYY-MM-DD. Example: '2024-01-01'.
endstringSeries: last UTC date, YYYY-MM-DD (at most 1000 samples).
intervalstring: 1h | 4h | 12h | 1d | 1w"1d"Series sampling step, in candle-timeframe notation.
time_utcstring"00:00"Series: UTC time of day of the first sample, HH:MM.
perspectivestring: geocentric | heliocentric | both"both"Geocentric, heliocentric, or both in one call (default).
bodiesarray 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).
aspectsvalueAspect offsets added to every line (+angle and -angle). Default: the planet's own line only (conjunction).
averagesarray 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_methodstring: arithmetic | circular"arithmetic"'arithmetic' mean of the 0-360 longitude values or 'circular' (vector) mean of the directions.
price_unitnumberScale 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_rangeobjectThe window of the value scale in which to list the projected levels, e.g. {min: 30000, max: 80000}.
price_range.minnumberLowest value on the scale to list.
price_range.maxnumberHighest value on the scale to list.
unwrapbooleanfalseSeries: continuous degrees (no 360 -> 0 jump), for plotting lines across a chart.
include_declinationbooleanfalseSeries: also a declination column per body.
formatstring: columns | rows"columns"Series layout: 'columns' (pandas.DataFrame(result['series'])) or 'rows' (one object per sample).
optionsobjectOptional zodiac settings.
options.zodiacstring: tropical | sidereal"tropical"'tropical' (default) or 'sidereal' (pair it with 'ayanamsa').
options.ayanamsastring: 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

FieldTypeDescription
result.settingsobjectSettings 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.subjectobjectSnapshot only: the resolved moment (UTC, Julian days, Delta T).
result.linesarraySnapshot 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_levelsarraySnapshot with price_unit: every projected value-scale level inside price_range, sorted, with its line id.
result.seriesobject | arraySeries only: 'columns' format = {time_utc: [...], timestamp: [...], <line id>: [...]}; 'rows' format = one object per sample.
result.countsobjectNumber of lines and projected levels (snapshot) or of samples and columns (series).
result.warningsarrayNotes 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.
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).

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.