有効期間とは

tabにおける「有効期間」とは、アイテムが持つ情報のうちの一つで、アイテムが利用可能な期間を表します。

またアイテムが利用可能な期間とは、例えばイベントの開催期間のようなもので、2013年1月の間のみ参加可能なイベントであれば、有効期間は「2013年1月1日〜2013年1月31日」となります。

有効期間を登録しておくことで、そのアイテムがいつからいつまで体験可能なのかを把握しやすくなり、更に有効期間が終了して体験不可能となったアイテムがAPIのレスポンスからフィルタリングされるなど、様々なメリットが生じます。

関連パラメータ

starting_date

有効期間の開始日時を表します。このパラメータが表現する日時は有効期間に含まれます。

ending_date

有効期間の終了日時を表します。このパラメータが表現する日時は有効期間に含まれます。

include_expired

有効期間を過ぎたアイテムを一覧に含むかどうかを表します。

• include_expired=true の場合 : 有効期間が終了したアイテムを一覧に含みます
• include_expired=false の場合 : 有効期間が終了したアイテムを一覧に含みません

有効期間によるアイテムのフィルタリング

有効期間が設定されたアイテムは、各種取得系のAPIごとに適切なフィルタリングをされて返却されます。

以下に各APIにおけるフィルタリングの挙動の一覧を示します。 ここで◯はフィルタリングなし(返却される)、×はフィルタリングあり(返却されない)を表します。

• API : リクエスト対象のAPI
• 開始前 : starting_date で設定された日時以前にリクエストが行われた場合
• 期間中 : starting_date で設定された日時以降、かつ ending_date で設定された日時以前にリクエストが行われた場合
• 終了後 : ending_date で設定された日時以降にリクエストが行われた場合

API	開始前	期間中	終了後
GET /api/1/areas/:area_id/items.json	◯	◯	×
GET /api/1/items/popular.json	◯	◯	×
GET /api/1/items/latest.json	◯	◯	×
GET /api/1/items/search.json	◯	◯	×
GET /api/1/items/:item_id/similar.json	◯	◯	×
GET /api/1/items/nearby.json	×	◯	×
GET /api/1/items/nearby_remind.json	×	◯	×
GET /api/1/items/:item_id/reclips.json	◯	◯	◯
GET /api/1/items/pickup.json	◯	◯	◯
GET /api/1/streams/:stream_id/items.json	◯	◯	※1
GET /api/1/users/:user_id/items/nearby.json	×	◯	×
GET /api/1/users/:user_id/items.json	◯	◯	×

※1 ログイン状態で、かつ自分の所有するtabを参照した場合は◯、それ以外の場合は×

注意事項

• tab APIでは全ての日時についてタイムゾーンをUTCとして入出力を行っているため、APIを介した有効期間の取得／登録は全てUTCの形で実施してください。

• 有効期間の開始日時と終了日時は必ず両方を指定するか、もしくは両方とも指定しない状態のみでの登録を受け付けています。開始日時と終了日時のうち、どちらか一方のみを指定したデータ登録はエラーとなりますのでご注意ください。