Python SDK

Install

pip install timenow

Quick Start

from timenow import TimeNowClient

client = TimeNowClient("http://localhost:8090")

# Get solar time for London
result = client.get_solar_time(lat=51.5074, lng=-0.1278)
print(result.solar_time)          # "2026-04-14T11:49:23"
print(result.civil_solar_offset_min)  # -10.6

# Social jetlag score
jetlag = client.get_jetlag(lat=39.47, lng=75.99)
print(jetlag.risk_level)          # "severe"

# Prayer times
prayers = client.get_prayer_times(lat=51.5074, lng=-0.1278, convention="mwl")
print(prayers.dhuhr.civil)        # "13:11"

Methods

Method	Parameters	Returns	API endpoint
`get_solar_time(lat, lng, utc=None)`	lat, lng, optional UTC	`SolarTimeResult`	`GET /solar`
`get_jetlag(lat, lng)`	lat, lng	`JetlagResult`	`GET /solar/jetlag`
`get_prayer_times(lat, lng, date=None, convention="mwl")`	lat, lng, date, convention	`PrayerTimesResult`	`GET /solar/prayer`
`get_almanac(lat, lng, year=None)`	lat, lng, optional year	`AlmanacResult`	`GET /solar/almanac`
`get_ical(lat, lng, days=30)`	lat, lng, days	`str` (iCal)	`GET /solar/ical`
`get_deviation_map(fmt="json")`	format	`dict` or `str`	`GET /world/deviation-map`
`health()`	—	`bool`	`GET /health`

Data Classes

@dataclass
class SolarTimeResult:
    latitude: float
    longitude: float
    utc: str
    solar_time: str
    civil_time: str
    equation_of_time_min: float
    civil_solar_offset_min: float
    timezone: str
    solar_noon_utc: str
    sunrise_utc: str
    sunset_utc: str

Error Handling

from timenow import TimeNowClient, TimeNowError

client = TimeNowClient("http://localhost:8090")

try:
    result = client.get_solar_time(lat=999, lng=0)  # invalid lat
except TimeNowError as e:
    print(e.status_code)  # 400
    print(e.message)      # "lat must be between -90 and 90"