True Solar Time API

https://your-host/api/v1

curl https://your-host/api/v1/solar-time \
  -H "X-API-Key: tst_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-03-30","local_time":"14:30","place_name":"Singapore"}'

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743350400

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 42 second(s).",
    "retry_after": 42
  }
}

{
  "true_solar_time": "13:51:06",
  "local_time": "14:30:00",
  "utc_time": "06:30:00",
  "utc_offset": "+08:00",
  "timezone": "Asia/Singapore",
  "dst": false,
  "date": "2026-03-30",
  "location": {
    "place_name": "Singapore",
    "display_name": "Singapore, Central Region, Singapore",
    "latitude": 1.3521,
    "longitude": 103.8198,
    "country_code": "SG"
  },
  "calculation": {
    "equation_of_time_minutes": -4.1,
    "longitude_correction_minutes": -64.8,
    "total_difference_minutes": -68.9
  },
  "solar_position": { "azimuth": 271.34, "elevation": 28.17 },
  "confidence": "HIGH",
  "historical_context_status": "found",
  "summary": "In Singapore, the Sun is running 1 hour 8 minutes 54 seconds behind the clock.",
  "historical_context": "Singapore adopted UTC+8 permanently in 1982...",
  "solar_context": "The Equation of Time is -4.1 min on this date...",
  "validation": "  \u2713 EoT within expected range\n  \u2713 Longitude correction within expected range",
  "share": {
    "text": "True Solar Time in Singapore on 30 Mar 2026 at 14:30 \u2192 13:51",
    "url_params": "date=2026-03-30&local_time=14:30&latitude=1.3521&longitude=103.8198",
    "url": "/?date=2026-03-30&local_time=14:30&latitude=1.3521&longitude=103.8198"
  }
}

{ "error": { "code": "MACHINE_READABLE_CODE", "message": "Human-readable description." } }

# 1. First request returns 409:
POST /api/v1/solar-time
{ "date": "2026-03-30", "local_time": "14:30", "place_name": "Springfield" }

# Response:
{ "error": { "code": "AMBIGUOUS_LOCATION", "message": "...", "candidates": [
    { "display_name": "Springfield, Illinois, US", "latitude": 39.7817, "longitude": -89.6501, "recommended": true },
    ...
  ]
}}

# 2. Resubmit with chosen candidate's coordinates:
POST /api/v1/solar-time
{ "date": "2026-03-30", "local_time": "14:30", "latitude": 39.7817, "longitude": -89.6501 }

curl -s -X POST https://your-host/api/v1/solar-time \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tst_your_key_here" \
  -d '{
    "date": "2026-03-30",
    "local_time": "14:30",
    "place_name": "Singapore"
  }'

curl -s -X POST https://your-host/api/v1/solar-time \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tst_your_key_here" \
  -d '{
    "date": "2026-03-30",
    "local_time": "14:30",
    "latitude": 1.3521,
    "longitude": 103.8198
  }'

GET /api/v1/solar-time?date=2026-03-30&local_time=14:30&latitude=1.3521&longitude=103.8198

import requests

resp = requests.post(
    "https://your-host/api/v1/solar-time",
    headers={"X-API-Key": "tst_your_key_here"},
    json={
        "date": "2026-03-30",
        "local_time": "14:30",
        "place_name": "Singapore",
    },
)
resp.raise_for_status()
data = resp.json()
print(data["true_solar_time"])   # "13:51:06"
print(data["summary"])

const resp = await fetch("https://your-host/api/v1/solar-time", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "tst_your_key_here",
  },
  body: JSON.stringify({
    date: "2026-03-30",
    local_time: "14:30",
    place_name: "Singapore",
  }),
});
const data = await resp.json();
console.log(data.true_solar_time); // "13:51:06"