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 egzersiz verisi türleri
Veri türü
  dataType
  filter parametresi		 Kayıt
türü		 Kullanılabilir
işlemler		 Kapsam Webhook
desteği		 Gerçek sıfırlar
desteği
Egzersiz
  exercise
  exercise 		Oturum list, get, reconcile, create, update, batchDelete activity_and_fitness

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): Duraklatılmış aralıklar hariç olmak üzere, antrenmanın gerçek aktif süresi. Standart biçimlendirme, Duration biçimini kullanır (örneğin, "1800s").

Özet metrikleri

İç içe yerleştirilmiş metricsSummary 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. pist koşuları 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ölme 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

Egzersiz oturumu oluşturmak, güncellemek veya içe aktarmak için exercise veri türü koleksiyonuna bir veri noktası yazın. create veri noktaları 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 takibi için veri okumak veya yazmak üzere uygulamanızın erişim jetonunda aşağıdaki OAuth kapsamlarını isteyin:

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

Yetkilendirme üstbilgilerinde gerekli bir kapsam eksikse Google Health API bir yetkilendirme hatası döndürür.

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 activeDuration ile startTime ve endTime arasındaki fark yerine activeDuration değerini kullanın. Bu sayede, duraklatılan 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.

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
Kalori ve enerji