Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Google Health API を使用してワークアウトエクスペリエンスを開発する

Google Health API は、exercise セッションデータ型を使用して、ユーザーのワークアウトセッションとエクササイズ履歴をトラッキングします。セッションは、アクティビティメタデータ、一時停止イベントと再開イベント、ラップまたはスプリット、サマリー指標をまとめるコンテナとして機能します。

ユーザーに最適なエクスペリエンスを提供するために、アプリケーションでワークアウトを読み取り、書き込み、構造化する方法を理解してください。

サポートされるデータタイプ

この API は、ワークアウトとアクティビティセッションをトラッキングするために、次のデータ型をサポートしています。

*表: Google Health API ワークアウトデータ型*
データの種類 `dataType` `filter` パラメータ	レコードタイプ	利用可能なオペレーション	スコープ	Webhook のサポート	真のゼロのサポート
エクササイズ `exercise` `exercise`	セッション	list、get、reconcile、create、update、batchDelete	`.activity_and_fitness.readonly` `.activity_and_fitness.writeonly`

サマリーフィールド（`metricsSummary`）	イントラデイテレメトリーデータ型の名前	API テレメトリーデータ型 ID
`caloriesKcal`	活動エネルギー消費量	`active-energy-burned`
`distanceMillimeters`	距離	`distance`
`steps`	手順	`steps`
`averageHeartRateBeatsPerMinute`	心拍数	`heart-rate`
`activeZoneMinutes`	アクティブゾーン時間	`active-zone-minutes`

ワークアウトセッション

毎日のアクティビティやワークアウトを exercise セッションデータポイントとして書き込みます。各データポイントは、セッション全体の概要、イベント間隔の詳細（一時停止や再開などのアクション）、サマリー指標（総距離、歩数、平均心拍数など）を提供します。

セッション属性

エクササイズデータポイントを構造化する場合は、次のコアコンポーネントを確認します。

セッション時間（interval）: ワークアウトセッション全体の開始時間と終了時間、およびその時点でのタイムゾーンオフセット。
アクティビティタイプ（exerciseType）: 実行されたアクティビティのカテゴリ（RUNNING、WALKING、BIKING、AEROBIC_WORKOUT など）。正確な種類のフィジカルトレーニングを指定します。
表示名（displayName）: ワークアウトセッションのわかりやすい名前（「午後のトレイルランニング」など）。
アクティブな期間（activeDuration）: 一時停止した間隔を除いた、ワークアウトの実際の活動時間。標準の形式では Duration 形式（たとえば、"1800s"）を使用します。

サマリー指標

metricsSummary ネストされたオブジェクトには、エクササイズセッションの全期間にわたって計算された合計指標と平均指標が含まれます。

caloriesKcal: ワークアウト中に消費されたアクティブカロリーの合計（キロカロリー（kcal）単位）。
distanceMillimeters: 移動距離の合計。単位間の精度を維持するためにミリメートル単位で測定されます。
steps: エクササイズ中に踏んだ歩数の合計。
averageHeartRateBeatsPerMinute: セッションのアクティブな時間帯のユーザーの平均心拍数。
activeZoneMinutes: ワークアウト中に獲得したアクティブゾーン時間の合計。
averageSpeedMillimetersPerSecond: 平均移動速度（ミリメートル / 秒）。
averagePaceSecondsPerMeter: セッションのアクティブな時間帯の平均ペース（秒 / メートル単位）。
elevationGainMillimeters: セッション中の獲得標高の合計。

ラップとスプリット

ラップを含むワークアウト（トラックランニングやプールでの水泳など）の場合は、splitSummaries を使用します。

各スプリットには次のものが含まれます。

特定の startTime と endTime。
実際のラップ時間を表す activeDuration。
そのセグメントのみを対象とする metricsSummary。
スプリットの境界を定義する splitType（DISTANCE、DURATION、MANUAL など）。

エクササイズイベント

アクティブな期間を正確に計算するには、exerciseEvents を使用して状態遷移（手動または自動の一時停止イベントなど）をトラッキングします。

各イベントには、タイムスタンプ（eventTime）とタイプが含まれます。

START / STOP: ユーザーが明示的にレコードを開始または停止したときの境界タイムスタンプを示します。
PAUSE / RESUME: セッションが手動で一時停止または再開された時点を示します。
AUTO_PAUSE / AUTO_RESUME: センサー駆動の自動一時停止/再開を示します。

ワークアウトセッションを作成する

ワークアウトセッションを作成、更新、インポートするには、exercise データ型コレクションにデータポイントを書き込みます。create データポイントエンドポイントを使用します。

REST 表現の例

次の例は、POST メソッドを使用してワークアウトセッションを書き込む方法を示しています。

リクエスト

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

レスポンス

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

GPS ルートと位置情報追跡

この API は、基本的なセッションの概要を exercise データポイント内に直接保存しますが、詳細な位置情報履歴と GPS ルート座標は別のストリームとして処理します。

屋外セッションの詳細なルートデータをダウンロードするには、exportExerciseTcx カスタムメソッドを呼び出します。このエンドポイントは、業界標準のトレーニングセンター XML（TCX） 形式でルートを返します。

GPS ルートをエクスポートする

リクエスト

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

レスポンス

Content-Type: application/tcx+xml を含む HTTP ペイロードと、ブラウザにファイルを保存するように指示するヘッダー。

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

必要なスコープと位置情報

GPS ルートと位置情報追跡 機能を使用するには、アプリが次の OAuth スコープをリクエストする必要があります。

既読: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
書き込み: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
既読: https://www.googleapis.com/auth/googlehealth.location.readonly

ガイドライン

ワークアウトトラッキングをアプリに統合する場合は、次の設計と実装のガイドラインに沿ってください。

アクティブな期間と合計期間

速度またはペースの指標を計算するには、startTime と endTime の差ではなく、常に activeDuration を使用します。これにより、一時停止した間隔が指標に影響することを防ぐことができます。

たとえば、ユーザーが 08:00 にワークアウトを開始し、08:35 に終了した場合、ワークアウトの合計経過時間は 2,100 秒になります。ユーザーがワークアウトを 5 分間（300 秒）一時停止した場合は、activeDuration を "1800s"（2,100 - 300）に設定します。この API は、アクティブな期間を使用して平均を計算します。つまり、総距離を 2,100 秒ではなく 1,800 秒で割ります。

位置情報を早めにリクエストする

アプリがワークアウトルートをマッピングする場合は、アクティビティとフィットネスのスコープに加えて、位置情報の権限と Google Health の location スコープをリクエストします。GPS エクササイズを確認する際に、アプリが位置情報スコープを必要とする理由をユーザーに説明します。

アプリが位置情報スコープ（https://www.googleapis.com/auth/googlehealth.location.readonly）をリクエストすると、Google OAuth によって同意プロンプトがユーザーに表示されます。ルートオーバーレイのレンダリングと GPS トラックファイル（TCX）のエクスポートには、この権限が必要であることをユーザーに説明します。ユーザーがアクティビティスコープを付与しても位置情報の利用許可を拒否した場合、exportExerciseTcx は承認エラーを返しますが、metricsSummary でセッションの集計にアクセスすることはできます。

Webhook を使用したリアルタイム同期

exercise データ型をサブスクライブして、新しいワークアウトデータが利用可能になったときに Webhook を使用してバックエンドに通知します。これにより、ワークアウト後のエクスペリエンスをリアルタイムでトリガーできます。

サーバーが Webhook 通知を受信すると、healthUserId とワークアウトの特定の物理時間間隔が含まれます。サーバーは通知を非同期で処理し、新しい exercise データポイントを /users/me/dataTypes/exercise/dataPoints エンドポイントからリクエストする必要があります。サブスクリプションの設定方法について詳しくは、 Webhook サブスクリプションをご覧ください。

一貫した指標を維持する

完全なワークアウト／トレーニング体験を提供するには、アプリが全体的な exercise セッションとともに高頻度テレメトリーデータポイントを同期する必要があります。これにより、ユーザーの 1 日の合計、過去の傾向、詳細グラフが完全に一致します。

テレメトリーとセッションを同期する（書き込みパス）

完了したワークアウトを Google Health API にインポートまたは書き込む場合は、複数ステップの書き込みパターンを実装します。

セッションを書き込む: データポイントを POST /users/me/dataTypes/exercise/dataPointsに投稿して、サマリーイベントをファイルに保存します。
時系列の間隔を書き込む: ワークアウト中に記録された詳細なデータポイント（1 分ごとの歩数や消費カロリーの間隔など）を、それぞれのコレクションに同時に書き込みます:
- POST /users/me/dataTypes/steps/dataPoints
- POST /users/me/dataTypes/active-energy-burned/dataPoints
- POST /users/me/dataTypes/heart-rate/dataPoints

グラフの詳細データをクエリする（読み取りパス）

特定のワークアウトセッションの過去のワークアウトダッシュボードまたはパフォーマンスグラフをレンダリングする場合は、セッションの時間枠を使用して詳細なテレメトリーをクエリします。

セッションの概要をクエリする: /users/me/dataTypes/exercise/dataPoints を呼び出して、ワークアウトの詳細と最終的な metricsSummary を取得します。
グラフの指標を取得する: ワークアウトの interval.startTime と interval.endTime を確認します。その特定の時間枠のテレメトリーコレクションに対して、セカンダリ GET 呼び出しを行います。
- GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
GPS ルートを取得する: セッションのメタデータに GPS データが存在することが示されている場合（exerciseMetadata.hasGps が true）、 exportExerciseTcx ヘルパーメソッドを呼び出してルート座標をダウンロードします。

主な指標

栄養素と水分補給

Google Health API を使用してワークアウト エクスペリエンスを開発する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

サポートされるデータタイプ

関連するテレメトリー データ型

ワークアウト セッション

セッション属性

サマリー指標

ラップとスプリット

エクササイズ イベント

ワークアウト セッションを作成する

REST 表現の例

リクエスト

レスポンス

GPS ルートと位置情報追跡

GPS ルートをエクスポートする

リクエスト

レスポンス

必要なスコープと位置情報

ガイドライン

アクティブな期間と合計期間

位置情報を早めにリクエストする

Webhook を使用したリアルタイム同期

一貫した指標を維持する

テレメトリーとセッションを同期する（書き込みパス）

グラフの詳細データをクエリする（読み取りパス）

Google Health API を使用してワークアウトエクスペリエンスを開発する

関連するテレメトリーデータ型

ワークアウトセッション

エクササイズイベント

ワークアウトセッションを作成する