Docs › Planetary longitude series (geocentric + heliocentric)

Planetary longitude series (geocentric + heliocentric)

Ecliptic longitudes of the planets at one moment or as a time series (1 hour to 1 week steps), geocentric and heliocentric, with optional angle offsets, multi-body averages and declinations.

POST https://astro-agent.dev/v1/astronomy/longitude-series · $0.20 per call · MCP tool longitude_series · Try it in the playground

Planetary longitudes as data: at a moment, or as a series of up to 1000 samples (columns ready for pandas). Geocentric apparent and heliocentric geometric, each with its speed and retrograde flag; optional offsets (longitude + angle), circular or arithmetic multi-body averages, unwrapped degrees for plotting, and declinations.

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

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: 1 hour, 4 hours, 12 hours, 1 day or 1 week.
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, lunar_node_mean, lunar_node_true)Bodies. Default: Sun..Pluto (geocentric), Mercury..Pluto with the Earth (heliocentric).
offsetsvalueAngles in degrees added to every longitude (+angle and -angle), 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: none (the longitude itself).
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.
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).
unwrapbooleanfalseSeries: continuous degrees (no 360 -> 0 jump), for plotting.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/longitude-series \
  -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/astronomy/longitude-series", 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/astronomy/longitude-series", {
  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:

d719979186951fab43b30da12b7dd497a533e4c38d3b51e3711f88a4670ae099

{
  "endpoint": "astronomy/longitude-series",
  "result": {
    "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
      ]
    },
    "settings": {
      "perspectives": [
        "geocentric"
      ],
      "bodies": {
        "geocentric": [
          "jupiter",
          "saturn"
        ]
      },
      "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",
      "interval": "1w",
      "samples": 53,
      "unwrap": false,
      "format": "columns",
      "columns": [
        "geo.jupiter",
        "geo.saturn"
      ],
      "unwrapped": null,
      "longitude_reference": "ecliptic longitude from the true equinox of date (0-360 degrees)"
    },
    "counts": {
      "samples": 53,
      "columns": 2
    }
  },
  "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": "4491c287b847efe6d8a50c61e6032bdb0e87e922f9cd22567a4c8499b90837ce",
    "result_sha256": "d719979186951fab43b30da12b7dd497a533e4c38d3b51e3711f88a4670ae099",
    "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, bodies, offsets, averages and their members, frames, line id format 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; speed, retrograde flag and declination on base lines).
result.seriesobject | arraySeries only: 'columns' format = {time_utc: [...], timestamp: [...], <line id>: [...]}; 'rows' format = one object per sample.
result.countsobjectNumber of lines (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).

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/longitude-series?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.