Try TimeTree API

TimeTree というカレンダーアプリを使用しています。

• TimeTree People

TimeTree には API がありますが、最初はイベントを取得する API がありませんでした。が、最近追加されました！

TimeTree ついに予定取得 API が！https://t.co/VRmhNfJRVC

— †深淵の覚醒者† (@lorentzca) January 28, 2020

そして Alexa スキルも公開されていました！

• Amazon.co.jp： TimeTree / タイムツリー: Alexaスキル

私はイベント取得 API を今から帰るボタンに使いたいと思っているので、

• 今から帰るボタン v2

それに先立って軽く触ってみます。

イベントの取得

イベントを取得するための認証方法として、現在アクセストークンと OAuth 認証の二つが用意されています。

• APIのはじめかた

今回はアクセストークンを使用してみます。アクセストークンはすぐ発行されるので環境変数にでも入れておきます。

当日以降の直近の予定は upcoming_events から取得できます。

• GET /calendars/:calendar_id/upcoming_events

curl コマンドのサンプルもあって親切！

$ curl https://timetreeapis.com/calendars/1234/upcoming_events?timezone=Asia/Tokyo&days=3&include=creator,label,attendees \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

calendar_id は対象のカレンダーを開いて、URL から確認できます。以下のようなイメージ。

• https://timetreeapp.com/calendars/\<calendar_id>

テストイベントを作成して取得してみます。結果は jq でいくつかに絞っています。

$ curl -s \
-H "Accept: application/vnd.timetree.v1+json" \
-H "Authorization: Bearer $TIMETREE_TOKEN" \
"https://timetreeapis.com/calendars/$calendar_id/upcoming_events?timezone=Asia/Tokyo&days=3&include=creator,label,attendees" \
| jq '.data[].attributes | {"title": .title, "all_day": .all_day, "start_at": .start_at, "end_at": .end_at, "start_timezone": .start_timezone, "end_timezone": .end_timezone}'
{
  "title": "test event 2",
  "all_day": false,
  "start_at": "2020-02-16T14:30:00.000Z",
  "end_at": "2020-02-16T15:30:00.000Z",
  "start_timezone": "Asia/Tokyo",
  "end_timezone": "Asia/Tokyo"
}
{
  "title": "test event 1",
  "all_day": false,
  "start_at": "2020-02-16T01:00:00.000Z",
  "end_at": "2020-02-16T02:00:00.000Z",
  "start_timezone": "Asia/Tokyo",
  "end_timezone": "Asia/Tokyo"
}

取れました！

で、最初パラメータで指定できるタイムゾーンの意味がよくわからなかったのですが、日付を跨ぐイベントと跨がないイベントを作成し、Asia/Tokyo と Etc/GMT それぞれの結果を取得してみたところなんとなくわかりました。

Asia/Tokyo

curl -s \
-H "Accept: application/vnd.timetree.v1+json" \
-H "Authorization: Bearer $TIMETREE_TOKEN" \
"https://timetreeapis.com/calendars/$calendar_id/upcoming_events?timezone=Asia/Tokyo&days=3&include=creator,label,attendees" \
| jq '.data[].attributes | {"title": .title, "all_day": .all_day, "start_at": .start_at, "end_at": .end_at, "start_timezone": .start_timezone, "end_timezone": .end_timezone}'

{
  "title": "test event 2",
  "all_day": false,
  "start_at": "2020-02-16T14:30:00.000Z",
  "end_at": "2020-02-16T15:30:00.000Z",
  "start_timezone": "Asia/Tokyo",
  "end_timezone": "Asia/Tokyo"
}

Etc/GMT

curl -s \
-H "Accept: application/vnd.timetree.v1+json" \
-H "Authorization: Bearer $TIMETREE_TOKEN" \
"https://timetreeapis.com/calendars/$calendar_id/upcoming_events?timezone=Etc/GMT&days=3&include=creator,label,attendees" \
| jq '.data[].attributes | {"title": .title, "all_day": .all_day, "start_at": .start_at, "end_at": .end_at, "start_timezone": .start_timezone, "end_timezone": .end_timezone}'

{
  "title": "test event 2",
  "all_day": false,
  "start_at": "2020-02-16T14:30:00.000Z",
  "end_at": "2020-02-16T15:30:00.000Z",
  "start_timezone": "Asia/Tokyo",
  "end_timezone": "Asia/Tokyo"
}
{
  "title": "test event 1",
  "all_day": false,
  "start_at": "2020-02-16T01:00:00.000Z",
  "end_at": "2020-02-16T02:00:00.000Z",
  "start_timezone": "Asia/Tokyo",
  "end_timezone": "Asia/Tokyo"
}

上記結果を見るに以下のような意味っぽい。

• レスポンスの start_at, end_at: パラメータで指定したタイムゾーンに関わらず協定世界時で表示される。
• レスポンスの start_timezone, end_timezone: (多分) イベント作成時に指定されたタイムゾーン。
• パラメータの timezone: API 呼び出し環境のタイムゾーン。
  • つまり、日本時間の 02/17 00:30 に upcoming_events API を timezone=AsiaTokyo パラメータをつけて実行した場合、API は 日本時間の 02/17 00:30 に実行されたとみなされ、02/17 中に開始または終了されるイベントを返す。
  • 一方で、日本時間の 02/17 00:30 に upcoming_events API を timezone=Etc/GMT パラメータをつけて実行した場合、API は 日本時間の 02/16 15:30 に実行されたとみなされ、02/16 中に開始または終了されるイベントを返す。

パラメータで指定したタイムゾーンとレスポンスのタイムゾーンが異なるのでちょっと混乱するかも (レスポンスにパラメータで指定したタイムゾーンは含まれないので時差込みでも取得結果に違いが発生しない場合、結果に変化が無いのでパラメータ指定した意味は？と感じる)。

例えばパラメータでタイムゾーンを Asia/Tokyo にした場合はレスポンスが以下のようになるとわかりやすいかも…。

• start_at, end_at のタイムスタンプを指定したタイムゾーンに合わせる。

{
  "title": "test event 2",
  "all_day": false,
  "start_at": "2020-02-16T23:30:00.000+09:00",
  "end_at": "2020-02-17T00:30:00.000+09:00",
  "start_timezone": "Asia/Tokyo",
  "end_timezone": "Asia/Tokyo"
}

上記解釈で間違ってたらスマソ。🙏

感想

TimeTree の予定取得 API はずっと待っていたので嬉しい！！

早く今から帰るボタンに使いたい。