Docs › Julian day, sidereal time, Delta T and time scales

Julian day, sidereal time, Delta T and time scales

One moment in every astronomical time scale: UTC, unix time, Julian day (UTC, UT1, TT, TDB), MJD, Julian centuries, Delta T, TAI-UTC, UT1-UTC, Greenwich and local mean and apparent sidereal time.

POST https://astro-agent.dev/v1/astronomy/time · $0.01 per call · MCP tool time_scales · Try it in the playground

For telescope control, data reduction and education: the Julian day in UTC, UT1, TT and TDB, the modified Julian day, Julian centuries since J2000 (TT), Delta T (TT - UT1), TAI - UTC and UT1 - UTC, Greenwich mean and apparent sidereal time and, with a longitude, the local ones; plus day of year and ISO week.

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
datetimestringyesThe moment: UTC ('2026-06-21T12:00:00Z'), with an explicit offset, or local civil time with latitude/longitude.
latitudenumberOptional: resolve a local time, and give the local sidereal time.
longitudenumberOptional, with latitude.
timezonestringIANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules).

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/time \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-06-21T12:00:00Z", "latitude": 48.8566, "longitude": 2.3522}'

Python

import os
import requests

body = {'datetime': '2026-06-21T12:00:00Z', 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/time", 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()

r = data["result"]
print("JD (TT)", r["julian_day"]["tt"], " MJD", r["modified_julian_day"])
print("GMST", r["sidereal_time"]["gmst_hours"], "h  LMST", r["sidereal_time"]["lmst_hours"], "h")
print("Delta T", r["delta_t_seconds"], "s")
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 = {"datetime": "2026-06-21T12:00:00Z", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/time", {
  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 r = data.result;
console.log("JD (TT)", r.julian_day.tt, " MJD", r.modified_julian_day);
console.log("GMST", r.sidereal_time.gmst_hours, "h  LMST", r.sidereal_time.lmst_hours, "h");
console.log("Delta T", r.delta_t_seconds, "s");
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:

c8ac6de4a246717203fe4a0726797836e00f564bd18282a704e7b06d7e2f404c

{
  "endpoint": "astronomy/time",
  "result": {
    "subject": {
      "time": {
        "local_input": "2026-06-21T12:00:00Z",
        "time_basis": "civil",
        "timezone": null,
        "timezone_source": "offset_in_datetime",
        "utc_offset": "+00:00",
        "is_dst": null,
        "utc": "2026-06-21T12:00:00Z",
        "julian_day_ut": 2461213.0,
        "julian_day_tt": 2461213.000801,
        "delta_t_seconds": 69.142,
        "time_known": true,
        "local_mean_time": "2026-06-21T12:09:24",
        "true_solar_time": "2026-06-21T12:07:35",
        "equation_of_time_minutes": -1.8173
      }
    },
    "settings": {
      "conventions": {
        "julian_day": "JD in UT1, TT and TDB; MJD = JD(UTC) - 2400000.5",
        "delta_t": "TT - UT1, seconds (Skyfield's IERS / Stephenson-Morrison-Hohenkerk 2016 tables)",
        "tai_minus_utc": "leap seconds; before 1972 UTC had no leap seconds and the value is the model's",
        "sidereal": "Greenwich mean (GMST) and apparent (GAST) sidereal time, hours (IAU 2006/2000A); local = Greenwich + east longitude / 15"
      }
    },
    "utc": "2026-06-21T12:00:00Z",
    "unix_seconds": 1782043200.0,
    "julian_day": {
      "utc": 2461213.0,
      "ut1": 2461213.0,
      "tt": 2461213.000801,
      "tdb": 2461213.000801
    },
    "modified_julian_day": 61212.5,
    "julian_centuries_tt_since_j2000": 0.264695,
    "delta_t_seconds": 69.1419,
    "tai_minus_utc_seconds": 37.0,
    "ut1_minus_utc_seconds": 0.0421,
    "sidereal_time": {
      "gmst_hours": 5.97997,
      "gast_hours": 5.980102,
      "longitude": 2.3522,
      "lmst_hours": 6.136783,
      "last_hours": 6.136915
    },
    "day_of_year": 172,
    "iso_week": "2026-W25"
  },
  "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": "73feea32a6325b368cd233f54f359c3d76e7c3fe058ffed001d987e601c0ce2a",
    "result_sha256": "c8ac6de4a246717203fe4a0726797836e00f564bd18282a704e7b06d7e2f404c",
    "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.subjectobjectThe resolved moment ('time': input, time zone and offset, UTC, Julian days, Delta T).
result.settingsobjectEvery convention.
result.utcstringUTC, ISO 8601.
result.unix_secondsnumberSeconds since 1970-01-01T00:00:00Z.
result.julian_dayobjectJulian day in utc, ut1, tt and tdb.
result.modified_julian_daynumberJD(UTC) - 2400000.5.
result.julian_centuries_tt_since_j2000number(JD(TT) - 2451545.0) / 36525.
result.delta_t_secondsnumberTT - UT1, seconds.
result.tai_minus_utc_secondsnumberLeap seconds (TAI - UTC).
result.ut1_minus_utc_secondsnumberUT1 - UTC, seconds.
result.sidereal_timeobjectgmst_hours, gast_hours and, with a place, longitude, lmst_hours, last_hours.
result.day_of_yearinteger1..366.
result.iso_weekstringISO 8601 week, e.g. 2026-W25.
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.