thirdtrail

thirdtrail

用于调用 thirdtrail API 的 Python 客户端：提供地球上任意位置的太阳、月亮、曙暮光、太阳辐照度和潮汐数据。太阳和月亮的时间会根据你传入的海拔进行校正。

pip install thirdtrail

from thirdtrail import Client

tt = Client(api_key="tt_live_…")

for day in tt.ephemerides(lat=53.3498, lon=-6.2603, elevation=20):
    print(day.date, day.sun.rise, day.sun.set)

为什么要考虑海拔

大多数日出 API 给出的是海平面观测者的时间。你所处的位置越高，视野就越远，太阳也就越早越过地平线。

在莫赫悬崖（214 m），时间差约为 三分钟，日出、日落以及每个黄金时段和蓝色时段的起止时间都会相应变化：

	海平面	海拔 214 m
日出	07:23:33	07:20:25
黄金时段，上午开始	06:56:51	06:53:42
月出	18:03:48	17:59:40

黄金时段持续 20 到 40 分钟，因此三分钟所占的比例不容忽视。知道海拔时，请传入 elevation。

你将获得什么

day.sun.rise                        # datetime, with its timezone offset intact
day.sun.golden_hour.morning.start
day.moon.phase.name                 # "Waxing Gibbous"
day.moon.phase.illumination         # 0.7376

时间戳以带时区的 datetime 对象返回，而不是字符串。客户端尚未建模的内容仍可通过 day.raw 和 day.response 获取，因此服务器端新增字段时，你可以在客户端支持之前使用它。

端点

tt.ephemerides(lat=…, lon=…, elevation=…, days=7)     # sun + moon + twilight
tt.prayer_times(lat=…, lon=…, school="mwl")           # five daily prayers
tt.solar(lat=…, lon=…, timestamp=…)                   # position + irradiance
tt.solar_path(lat=…, lon=…, interval="5m")            # the sun's arc, sampled
tt.solar_dli(lat=…, lon=…, from_date=…, to_date=…)    # Daily Light Integral
tt.tide_heights(lat=…, lon=…, step="10m")             # water height series
tt.tide_extremes(lat=…, lon=…)                        # high and low waters
tt.tide_window(lat=…, lon=…, elevation=…)             # tides + sun + moon
tt.tide_constituents(lat=…, lon=…)                    # harmonic constants

潮汐数据不接受海拔参数，但有一个例外

tide_heights 和 tide_extremes 有意不提供 elevation 参数，因为你站得有多高并不会改变海面高度。如果传入该参数，会得到 TypeError，而不是被静默忽略。

tide_window 是个例外，因为它返回的数据中有一半是太阳和月亮数据：

for day in tt.tide_window(lat=52.9715, lon=-9.4309, elevation=214, days=3):
    print(day.date, day.sun.golden_hour.morning.start)
    for t in day.low_waters:
        print("  low water", t.time, t.height_m)

潮汐高度以相对于**平均海平面（而非海图基准面）**的米数表示，且不包括天气导致的风暴潮。请勿用于导航。

错误

每种失败都有各自的异常类，因此你可以捕获所需的异常，而不必解析错误消息：

from thirdtrail import PlanLimitExceeded

try:
    tt.tide_extremes(lat=51.5, lon=-2.7, days=90)
except PlanLimitExceeded as e:
    tt.tide_extremes(lat=51.5, lon=-2.7, days=e.limit)   # e.limit == 31

AuthenticationError（401）、PermissionDenied（403，当前订阅层级不包含此权限）、PlanLimitExceeded 和 InvalidRequest（400）、RateLimited（429）、DataUnavailable（503）、ServerError（5xx）。它们都继承自 ThirdtrailError。

瞬时故障和 429 错误会通过退避机制重试。订阅限额不会触发重试，因为相同的请求每次都会以相同方式失败。

密钥

前往 thirdtrail.life/apis/keys/ 创建密钥。一个密钥对应一个订阅，因此只能用于一个 API；使用潮汐密钥调用太阳端点会得到 PermissionDenied。

每个 API 都提供免费层级。

尚未涵盖的内容

此客户端尚未涵盖批量（POST）端点、iCalendar 订阅源或 webhook 管理。对于这些功能，请直接调用 REST API；完整规范以 OpenAPI 3.1 发布。

正在使用 AI Agent？这里有一个 MCP 服务，可将相同的数据作为工具提供。

许可证

MIT