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）では、その差は約 3 分です。日の出、日の入り、ゴールデンアワーとブルーアワーのすべての境界時刻も、それに応じて変わります。

	海面	標高 214 m
日の出	07:23:33	07:20:25
ゴールデンアワー、午前の開始	06:56:51	06:53:42
月の出	18:03:48	17:59:40

ゴールデンアワーは20〜40分続くため、3分は無視できない差です。標高がわかる場合は、必ず 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/ で作成してください。 キーは1つのサブスクリプションに紐付いているため、利用できる API は1つです。Tides キーで太陽のエンドポイントを呼び出すと、PermissionDenied が発生します。

すべての API に無料プランがあります。

未対応の機能

このクライアントは、バルク（POST）エンドポイント、iCalendar フィード、Webhook 管理にはまだ対応していません。これらを利用するには、REST API を直接呼び出してください。完全な仕様は OpenAPI 3.1 として公開されています。

AI エージェントを使用していますか？同じデータをツールとして公開する MCP サーバー があります。

ライセンス

MIT