> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt > Use this file to discover all available pages before exploring further. # 日付範囲とタイムゾーン > Profound API で日付とタイムゾーンを扱う方法 ## 概要システム内のすべてのデータは UTC で保存されていますが、処理は EST(米国東部標準時)のスケジュールで実行されます。ユースケースに応じて正しいデータをクエリするには、日付範囲の仕組みを理解することが重要です。タイムゾーンの誤った扱いは、API レスポンスでデータが欠落したり、予期しないデータが含まれたりする最も一般的な原因です。このガイドをよくお読みください。 ## システムの動作 ### データ処理のスケジュールシステムは EST タイムゾーンに従ってデータを処理します。 * EST の 1 月 1 日の「1 日」は **00:00 EST**(05:00 UTC)に始まります * EST の 1 月 1 日の「1 日」は **23:59 EST**(翌日の 04:59 UTC)に終わりますすべてのデータは、UTC タイムスタンプでデータベースに保存されます。 ### サポートされる日付形式 API は複数の形式の日付を受け付けます。 1. **日付のみ**(日単位のクエリに推奨): `2025-01-01` 2. **タイムゾーンなしの日付と時刻**: `2025-01-01T00:00:00` 3. **UTC タイムゾーン付きの日付と時刻**: `2025-01-01T05:00:00Z` ## 日付の解釈方法 ### タイムゾーンを指定しない場合 **タイムゾーンなし**(`Z` サフィックスなし)で日付を指定すると、API はそれを **EST** として解釈します。 ```json theme={null} { "start_date": "2025-01-01", "end_date": "2025-01-31" } ``` **処理内容:** * `2025-01-01` → `2025-01-01T00:00:00 EST` として解釈 → `2025-01-01T05:00:00Z` UTC に変換 * `2025-01-31` → `2025-01-31T00:00:00 EST` として解釈 → `2025-01-31T05:00:00Z` UTC に変換これはシステムにおける「日」の定義と一致しており、ほとんどのユースケースで**推奨される方法**です。 ### UTC タイムゾーン(Z サフィックス)を指定する場合 **Z サフィックス付き**で日付を指定すると、API はそれを**文字どおりの UTC** として解釈します。 ```json theme={null} { "start_date": "2025-01-01T00:00:00Z", "end_date": "2025-02-01T00:00:00Z" } ``` **処理内容:** * `2025-01-01T00:00:00Z` → UTC のままそのまま使用 * `2025-02-01T00:00:00Z` → UTC のままそのまま使用 UTC タイムスタンプ(Z 付き)を使用する場合は、EST から UTC への変換を手動で行う必要があります。この方法は後方互換性のために残されていますが、新しいインテグレーションには**推奨されません**。 ## 例 ### 正しい例: 2025 年 1 月のデータをクエリする(EST の日) ```json theme={null} { "start_date": "2025-01-01", "end_date": "2025-02-01" } ``` これにより、次の範囲のすべてのデータが返されます。 * 開始: 1 月 1 日 00:00 EST(1 月 1 日 05:00 UTC) * 終了: 2 月 1 日 00:00 EST(2 月 1 日 05:00 UTC) 範囲は終端を含みます(`<=`)が、通常データのタイムスタンプがちょうど 00:00 になることはないため、実質的に 1 月全体を取得できます。 ### 誤った例: UTC の午前 0 時で 2025 年 1 月をクエリする ```json theme={null} { "start_date": "2025-01-01T00:00:00Z", "end_date": "2025-02-01T00:00:00Z" } ``` これにより、次の範囲のデータが返されます。 * 開始: 12 月 31 日 19:00 EST(1 月 1 日 00:00 UTC) * 終了: 1 月 31 日 19:00 EST(2 月 1 日 00:00 UTC) **問題点:** 開始時に 5 時間分が欠落し、終了時に不要な 5 時間分が含まれてしまいます。 ### 正しい例: UTC で 2025 年 1 月をクエリする(手動変換) UTC タイムスタンプを使用する必要がある場合は、EST のオフセットを考慮する必要があります。 ```json theme={null} { "start_date": "2025-01-01T05:00:00Z", "end_date": "2025-02-01T05:00:00Z" } ``` これで 1 月全体(EST の日)を正しく取得できますが、タイムゾーンの計算を手動で行う必要があります。 ## 時間範囲 ### 日付のみの形式では午前 0 時がデフォルト日付のみの形式を使用する場合、時刻はデフォルトで `00:00:00` になります。 ```json theme={null} { "start_date": "2025-01-01" // Equivalent to 2025-01-01T00:00:00 EST } ``` ### 正確な時刻を指定するより細かいクエリを行うために、正確な時刻を指定できます。 ```json theme={null} { "start_date": "2025-01-01T08:00:00", // 8 AM EST "end_date": "2025-01-01T17:00:00" // 5 PM EST } ``` これにより、1 月 1 日の午前 8 時から午後 5 時(EST)までのデータをクエリします。 ### 日付範囲の動作日付範囲は両端を**含みます** `(start <= x <= end)`。 ```json theme={null} { "start_date": "2025-01-01", "end_date": "2025-01-02" } ``` これには次が含まれます。 * 1 月 1 日全体(00:00 EST 以降) * 1 月 2 日のちょうど 00:00 EST * データには 1 日を通してタイムスタンプが付与されるため、通常ちょうど 00:00 のデータは存在せず、実際には 1 月 1 日全体を取得することになります 1 日分をクエリするには、`end_date` を翌日の 00:00 に設定します。 ## ベストプラクティス **推奨:** 日単位のクエリには、タイムゾーンなしの日付のみの形式を使用する ```json theme={null} { "start_date": "2025-01-01", "end_date": "2025-02-01" } ``` **推奨:** 日中のクエリには、タイムゾーンなしの日時を使用する ```json theme={null} { "start_date": "2025-01-15T09:00:00", "end_date": "2025-01-15T17:00:00" } ``` **推奨:** 時間単位のレポートクエリ([Agent Analytics](/ja-jp/rest-api/examples/agent-analytics) の **V2 (hourly)** タブを参照)には、タイムゾーンなしの日時を使用する ```json theme={null} { "start_date": "2025-01-15T14:00:00", "end_date": "2025-01-15T14:59:59" } ``` **端数オフセットのタイムゾーンのユーザー:** `/v2/reports/*` で時間単位の粒度でクエリする場合、ローカルの 1 時間分の完全なデータを取得するには、連続する 2 時間分をクエリしてください。詳細は [端数オフセットのタイムゾーン](#fractional-offset-timezones) を参照してください。 **避けるべき方法:** UTC オフセットの影響を理解していない限り、Z サフィックスは使用しないでください ```json theme={null} { "start_date": "2025-01-01T00:00:00Z", // Probably not what you want "end_date": "2025-02-01T00:00:00Z" } ``` ## 夏時間 EST は夏時間(DST)を採用しています。 * **標準時(EST):** UTC-5(通常 11 月〜3 月) * **夏時間(EDT):** UTC-4(通常 3 月〜11 月) API は DST の切り替えを自動的に処理します。タイムゾーンなしで日付を指定すると、UTC への変換時に、その日付で DST が有効だったかどうかが考慮されます。 **DST 期間中の例:** ```json theme={null} { "start_date": "2025-07-01" // Interpreted as EDT (UTC-4) } ``` → `2025-07-01T04:00:00Z` UTC に変換されます(DST のため 05:00 ではありません) ## 端数オフセットのタイムゾーン一部のタイムゾーンでは、1 時間単位ではなく端数の UTC オフセットが使用されています。 | タイムゾーン | UTC オフセット | | - | - | | インド標準時(IST) | +5:30 | | アフガニスタン時間(AFT) | +4:30 | | ミャンマー時間(MMT) | +6:30 | | ネパール時間(NPT) | +5:45 | | チャタム諸島(CHAST) | +12:45 | | マルキーズ諸島(MART) | -9:30 | 時間単位のバケットは UTC の 1 時間単位の境界に揃えられているため、これらのタイムゾーンにおけるローカルの 1 時間は、常に 2 つの時間バケットにまたがります。任意のローカルの 1 時間分の完全なデータを取得するには、**連続する 2 時間分**をクエリする必要があります。 ### 例: IST の午後 2 時をクエリする IST は UTC+5:30 のため、IST の午後 2 時 = 08:30 UTC です。IST の午後 2 時から午後 3 時まで(08:30〜09:30 UTC)の 1 時間は、2 つの UTC 時間バケットにまたがります。 * **08:00〜08:59 UTC**(最初の 30 分: IST の午後 2 時〜午後 2 時 30 分を含む) * **09:00〜09:59 UTC**(最後の 30 分: IST の午後 2 時 30 分〜午後 3 時を含む) 1 時間分すべてを取得するには、両方のバケットをクエリします。 ```json theme={null} { "start_date": "2025-01-15T08:00:00Z", "end_date": "2025-01-15T09:59:59Z" } ``` これは、`/v2/reports/*` で**時間単位の粒度**でクエリする場合に該当します。端数オフセットのタイムゾーンにいて時間単位でデータをリクエストする場合は、隣接するバケットに含まれるデータの欠落を防ぐため、必ず連続する 2 時間分をリクエストしてください。 ## トラブルシューティング ### 日の境界でデータが欠落する **問題:** 1 月 1 日をクエリしているのに、最初または最後の数時間分が欠落している。 **解決策:** `Z` サフィックスを使用していないことを確認してください。`"start_date": "2025-01-01T00:00:00Z"` ではなく `"start_date": "2025-01-01"` を使用します。 ### 前日/翌日のデータが含まれる **問題:** 日単位のクエリに、隣接する日のデータが含まれている。 **解決策:** UTC の午前 0 時に `Z` サフィックスを付けて使用している可能性があります。これは EST の日と一致しません。タイムゾーンサフィックスを削除してください。 ### 予期しない DST の動作 **問題:** DST の切り替え時に、クエリに 1 時間のずれが生じる。 **解決策:** タイムゾーンなしの日付を使用し、API に DST を自動的に処理させてください。UTC を使用する必要がある場合は、EST(-5)と EDT(-4)でオフセットが変わることに注意してください。 ## 今後の変更今後の API バージョンでは、複数のタイムゾーンでのクエリを可能にするため、完全な ISO 8601 タイムゾーンオフセット(例: `-05:00`、`+09:00`)のサポートを予定しています。その時点で、タイムゾーン指定のない日付は非推奨となります。現時点では、タイムゾーンなしの日付を使用し、EST への変換を API に任せる方法を推奨します。