Docs › Local time resolver (historical time zones)
Local time resolver (historical time zones)
Local time + place -> exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time.
POST https://astro-agent.dev/v1/time/resolve · $0.01 per call · MCP tool resolve_birth_time
· Try it in the playground
The step LLMs most often get wrong. Resolves the IANA time zone from coordinates, applies the offset in force on that date (historical DST, Local Mean Time before standard time), flags ambiguous or non-existent local times instead of guessing, and returns Julian Days (UT/TT), Delta T, Local Mean Time, true (apparent) solar time and the equation of time.
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 | | Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'. | |
date | string | | YYYY-MM-DD (use with 'time' instead of 'datetime'). | |
time | string | | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). | |
latitude | number | | Decimal degrees, north positive. | |
longitude | number | | Decimal degrees, east positive. | |
timezone | string | | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. | |
time_basis | string: civil | utc | lmt | true_solar | "civil" | What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time. | |
ambiguous_time | string: earlier | later | "earlier" | Which occurrence to use when a local time happens twice (DST fall-back). |
Example request
curl
curl -s https://astro-agent.dev/v1/time/resolve \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"datetime": "1976-07-04T12:00", "latitude": 40.7128, "longitude": -74.006}'Python
import os
import requests
body = {'datetime': '1976-07-04T12:00', 'latitude': 40.7128, 'longitude': -74.006}
r = requests.post("https://astro-agent.dev/v1/time/resolve", 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()
t = data["result"]["time"]
print(t["utc"], t["timezone"], t["utc_offset"], "Delta T", t["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": "1976-07-04T12:00", "latitude": 40.7128, "longitude": -74.006};
const res = await fetch("https://astro-agent.dev/v1/time/resolve", {
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 t = data.result.time;
console.log(t.utc, t.timezone, t.utc_offset, "Delta T", t.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:
05d60071b590fcb43c222ee4db255843a843b790d8d7bf7120a3c15543d6d725
{
"endpoint": "time/resolve",
"result": {
"time": {
"local_input": "1976-07-04T12:00",
"time_basis": "civil",
"timezone": "America/New_York",
"timezone_source": "resolved_from_coordinates",
"utc_offset": "-04:00",
"is_dst": true,
"utc": "1976-07-04T16:00:00Z",
"julian_day_ut": 2442964.166669,
"julian_day_tt": 2442964.167213,
"delta_t_seconds": 47.007,
"time_known": true,
"local_mean_time": "1976-07-04T11:03:58",
"true_solar_time": "1976-07-04T10:59:34",
"equation_of_time_minutes": -4.4035
},
"location": {
"latitude": 40.7128,
"longitude": -74.006
}
},
"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": "3225b3488a6a77a219868b4eae5277d1bb8acc2b7381bfbf57909829f82c702c",
"result_sha256": "05d60071b590fcb43c222ee4db255843a843b790d8d7bf7120a3c15543d6d725",
"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.time | object | Resolved time: local input, IANA time zone and how it was found, historical UTC offset, DST flag, UTC instant, Julian days (UT and TT), Delta T, local mean time, true solar time and the equation of time. |
result.location | object | The latitude and longitude used, in decimal degrees. |
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.