Google Health API ile Egzersiz Deneyimleri Geliştirme

Google Health API, exercise oturum veri türünü kullanarak kullanıcı antrenman oturumlarını ve egzersiz geçmişini izler. Oturum, etkinlik meta verilerini, duraklatma ve devam ettirme etkinliklerini, turları veya bölümleri ve özet metrikleri bir araya getiren bir kapsayıcı görevi görür.

Kullanıcılarınıza en iyi deneyimi sunmak için uygulamanızdaki antrenmanları nasıl okuyacağınızı, yazacağınızı ve yapılandıracağınızı öğrenin.

Desteklenen veri türleri

API, egzersizleri ve aktivite oturumlarını izlemek için aşağıdaki veri türünü destekler:

Tablo: Google Health API Egzersizleri veri türleri
Veri türü Kullanılabilir
işlemler		 Kapsam
Egzersiz
dataType: exercise
filter parameter: exercise
Kayıt türü: Oturum

Uyumlu cihazlar
list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

Egzersiz oturumları kapsayıcı olarak exercise veri türünü kullanırken, normal egzersiz izleyiciler oturum sırasında ayrıntılı ve yüksek frekanslı telemetri verileri yazar ve okur. Bu ölçümler (ör. kalp atış hızı veya adım sayısı) kendi veri türleri kullanılarak okunmalı veya yazılmalıdır.

Aşağıdaki tabloda, metricsSummary veri türünün exercise nesnesindeki alanlar, Google Health API'nin ilgili ham telemetri veri türleriyle eşlenir:

Özet alanı (metricsSummary) Gün içi telemetri veri türü adı API telemetri veri türü kimliği
caloriesKcal Harcanan aktif enerji active-energy-burned
distanceMillimeters Mesafe distance
steps Adımlar steps
averageHeartRateBeatsPerMinute Nabız heart-rate
activeZoneMinutes Aktif Bölge Dakikası active-zone-minutes

Aşağıdaki bölümlerde, REST gösterim örnekleri, GPS rotası işleme ve entegrasyon yönergeleri dahil olmak üzere exercise veri türüyle ilgili teknik ayrıntılar verilmektedir.

Antrenman oturumları

Günlük aktiviteleri veya antrenmanları exercise oturum veri noktaları olarak yazın. Her veri noktası genel oturumu tanımlar, etkinlik aralıklarını (ör. duraklatma ve devam ettirme işlemleri) ayrıntılandırır ve özet metrikler (ör. toplam mesafe, adım sayısı ve ortalama kalp atış hızı) sağlar.

Oturum özellikleri

Egzersiz verisi noktası oluştururken aşağıdaki temel bileşenleri doğrulayın:

  • Oturum Süresi (interval): Genel antrenman oturumunun başlangıç ve bitiş zamanı ile bu noktalarda etkin olan saat dilimi farkları.
  • Etkinlik Türü (exerciseType): Yapılan etkinliğin kategorisi (ör. RUNNING, WALKING, BIKING veya AEROBIC_WORKOUT). Fiziksel eğitimin tam türünü belirtin.
  • Görünen Ad (displayName): Antrenman seansı için kullanıcı dostu bir ad (örneğin, "Öğleden Sonra Patika Koşusu").
  • Aktif Süre (activeDuration): Antrenmanın duraklatılmış aralıklar hariç gerçek aktif süresi. Standart biçimlendirme, Duration biçimini kullanır (örneğin, "1800s").

Özet metrikleri

metricsSummary iç içe yerleştirilmiş nesnesi, egzersiz oturumunun tamamı boyunca hesaplanan toplam ve ortalama metrikleri içerir:

  • caloriesKcal: Egzersiz sırasında yakılan toplam aktif kalori miktarı, kilokalori (kcal) cinsinden ölçülür.
  • distanceMillimeters: Birimler arasında yüksek hassasiyeti korumak için milimetre cinsinden ölçülen toplam mesafe.
  • steps: Egzersiz sırasında atılan toplam adım sayısı.
  • averageHeartRateBeatsPerMinute: Oturumun etkin dakikaları boyunca kullanıcının ortalama kalp atış hızı.
  • activeZoneMinutes: Egzersiz sırasında kazanılan toplam aktif bölge dakikası.
  • averageSpeedMillimetersPerSecond: Saniyede milimetre cinsinden ortalama hareket hızı.
  • averagePaceSecondsPerMeter: Oturumun aktif dakikaları boyunca ortalama hız (metre başına saniye cinsinden ölçülür).
  • elevationGainMillimeters: Seans sırasındaki toplam çıkılan yükseklik.

Turlar ve bölümler

Turları içeren antrenmanlar (ör. pistte koşma veya havuzda yüzme) için splitSummaries simgesini kullanın.

Her bölüm şunları içerir:

  • Belirli bir startTime ve endTime.
  • Gerçek tur süresini gösteren bir activeDuration.
  • Yalnızca bu segmentle sınırlı bir metricsSummary.
  • Bölünme sınırlarını tanımlamak için splitType (ör. DISTANCE, DURATION veya MANUAL).

Egzersiz etkinlikleri

Etkin süreyi doğru şekilde hesaplamak için exerciseEvents kullanarak durum geçişlerini (ör. manuel veya otomatik duraklatma etkinlikleri) izleyin.

Her etkinlikte zaman damgası (eventTime) ve tür bulunur:

  • START / STOP: Kullanıcının kaydı açıkça başlattığı veya durdurduğu zaman damgalarını gösterir.
  • PAUSE / RESUME: Oturumun manuel olarak duraklatıldığı veya devam ettirildiği zamanı gösterir.
  • AUTO_PAUSE / AUTO_RESUME: Sensör kaynaklı otomatik duraklatma/devam ettirme işlemlerini gösterir.

Antrenman seansı yazma

Antrenman seansı oluşturmak, güncellemek veya içe aktarmak için exercise veri türü koleksiyonuna bir veri noktası yazın. create dataPoints uç noktasını kullanın.

REST gösterimi örneği

Aşağıdaki örnekte, POST yöntemi kullanılarak antrenman seansının nasıl yazılacağı gösterilmektedir:

İstek

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
        }
      }
    ]
  }
}

Yanıt

{
  "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 rotaları ve konum takibi

API, temel oturum özetlerini doğrudan exercise veri noktasında kaydeder ancak ayrıntılı konum geçmişini ve GPS rota koordinatlarını ayrı bir akış olarak işler.

Açık hava oturumunun ayrıntılı rota verilerini indirmek için exportExerciseTcx özel yöntemini çağırın. Bu uç nokta, rotayı sektör standardı olan Training Center XML (TCX) biçiminde döndürür.

GPS rotasını dışa aktarma

İstek

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

Yanıt

Tarayıcıya dosyayı kaydetmesini söyleyen Content-Type: application/tcx+xml ve başlıklarını içeren bir HTTP yükü.

<?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>

Gerekli kapsamlar ve konum

GPS rotaları ve konum izleme özelliğini kullanmak için uygulamanızın aşağıdaki OAuth kapsamlarını istemesi gerekir:

  • Okuma: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Yazma: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Okuma: https://www.googleapis.com/auth/googlehealth.location.readonly

Yönergeler

Antrenman takibini uygulamanıza entegre ederken aşağıdaki tasarım ve uygulama kurallarına uyun.

Etkin süre ve toplam süre

Hız veya tempo metriklerini hesaplamak için her zaman startTime ile endTime arasındaki fark yerine activeDuration değerini kullanın. Bu sayede, duraklatılmış aralıkların metriklerinizi çarpıtması önlenir.

Örneğin, bir kullanıcı 08:00'da antrenmana başlar ve 08:35'te bitirirse antrenmanın toplam süresi 2.100 saniye olur. Kullanıcı antrenmanı 5 dakika (300 saniye) duraklattıysa activeDuration değerini "1800s" (2.100 - 300) olarak ayarlayın. API, ortalamaları hesaplamak için etkin süreyi kullanır ve toplam mesafeyi 2.100 yerine 1.800 saniyeye böler.

Hız ve tempo hesaplama

Google Health API, hızı ve tempoyu hesaplamak için standart formüller kullanır:

  • Hız = distance / time(hour)
  • Tempo = time(seconds) / distance

İstekte belirtilen Accept-Language başlığı, mesafe birimini belirler.

Konum bilgisini erkenden isteme

Uygulamanız antrenman rotalarını haritalandırıyorsa aktivite ve fitness kapsamına ek olarak konum izinleri ve Google Sağlık location kapsamı isteyin. Uygulamanızın GPS egzersizlerini incelerken neden konum kapsamı gerektirdiğini kullanıcılara açıklayın.

Uygulamanız konum kapsamını (https://www.googleapis.com/auth/googlehealth.location.readonly) istediğinde Google OAuth, kullanıcıya bir izin istemi gösterir. Kullanıcılarınıza bu iznin, rota katmanlarını oluşturmak ve GPS iz dosyalarını (TCX) dışa aktarmak için gerekli olduğunu açıklayın. Bir kullanıcı etkinlik kapsamı izni verip konum iznini reddederse exportExerciseTcx, yetkilendirme hatası döndürür ancak metricsSummary'deki oturum toplamlarına erişmeye devam edebilirsiniz.

Webhook'ları kullanarak anlık senkronizasyon

Yeni antrenman verileri kullanıma sunulduğunda arka uç sisteminizi webhook'ları kullanarak bilgilendirmek için exercise veri türüne abone olun. Bu sayede, antrenman sonrası deneyimleri gerçek zamanlı olarak tetikleyebilirsiniz.

Sunucunuz bir webhook bildirimi aldığında healthUserId ve antrenmanın belirli fiziksel zaman aralığını içerir. Sunucunuz, bildirimi eşzamansız olarak işlemeli ve ardından exercise uç noktasından yeni /users/me/dataTypes/exercise/dataPoints veri noktasını istemelidir. Abonelikleri ayarlama hakkında ayrıntılı bilgi için Webhook abonelikleri başlıklı makaleyi inceleyin.

Metrikleri tutarlı tutma

Eksiksiz bir antrenman deneyimi sunmak için uygulamanızın, genel exercise seansıyla birlikte yüksek frekanslı telemetri veri noktalarını senkronize etmesi gerekir. Bu sayede kullanıcının günlük toplamları, geçmiş trendleri ve ayrıntı grafikleri tamamen uyumlu kalır.

Telemetri ve oturumları senkronize etme (yazma yolu)

Tamamlanmış bir antrenmanı Google Health API'ye aktarırken veya yazarken çok adımlı bir yazma modeli uygulayın:

  1. Oturumu yazma: Bir veri noktası yayınlayarak özet etkinliğini kaydedin POST /users/me/dataTypes/exercise/dataPoints.
  2. Zaman serisi aralıklarını yazma: Antrenman sırasında kaydedilen ayrıntılı veri noktalarını (ör. dakikaya göre adım sayısı veya yakılan kalori aralıkları) eşzamanlı olarak ilgili koleksiyonlara yazın:
    • POST /users/me/dataTypes/steps/dataPoints
    • POST /users/me/dataTypes/active-energy-burned/dataPoints
    • POST /users/me/dataTypes/heart-rate/dataPoints

Grafiklerle ilgili ayrıntılı verileri sorgulama (okuma yolu)

Belirli bir antrenman oturumu için geçmiş antrenman kontrol panellerini veya performans grafiklerini oluştururken oturumun zaman aralığını kullanarak ayrıntılı telemetriyi sorgulayın:

  1. Oturum özetlerini sorgulama: Genel antrenman ayrıntılarını ve son metricsSummary değerini getirmek için Call /users/me/dataTypes/exercise/dataPoints işlevini kullanın.
  2. Grafik metriklerini getirme: Antrenmanın interval.startTime ve interval.endTime değerlerini inceleyin. Belirli bir zaman aralığı için telemetri koleksiyonlarına ikincil GET çağrıları yapın:
    • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
  3. GPS rotalarını getirme: Oturumun meta verileri GPS verilerinin mevcut olduğunu gösteriyorsa (exerciseMetadata.hasGps, true ise) rota koordinatlarını indirmek için exportExerciseTcx yardımcı yöntemini çağırın.
Önceki
Android Vitals
Sonraki
Beslenme ve sıvı alımı