$ 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 はずっと待っていたので嬉しい！！

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

イベントの取得

感想

Sign up for more like this.