Google Health API ile Egzersiz Deneyimleri Geliştirme

Google Health API, exercise oturum veri türünü kullanarak kullanıcıların antrenman seanslarını ve egzersiz geçmişini takip eder. 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ızda antrenmanları nasıl okuyacağınızı, yazacağınızı ve yapılandıracağınızı öğrenin.

Desteklenen veri türleri

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

Tablo: Google Health API Antrenmanlar 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

Antrenman oturumları, kapsayıcı olarak exercise veri türünü kullanırken giyilebilir cihazlar da oturum sırasında ayrıntılı ve yüksek frekanslı telemetri verileri kaydeder. Google Health API'de bu ayrıntılı gün içi telemetri veri türleri salt okunurdur ve doğrudan kendi REST uç noktaları üzerinden oluşturulamaz veya değiştirilemez. REST API aracılığıyla bir antrenman seansı yazarken exercise veri noktasının metricsSummary nesnesinde toplu antrenman metriklerini iletin.

Aşağıdaki tabloda, exercise.metricsSummary içindeki özet alanları, ilgili antrenmanın zaman aralığı için sorgulayabileceğiniz salt okunur gün içi telemetri veri türleriyle eşlenmiştir:

Özet alanı (metricsSummary) Gün içi telemetri verisi türü adı API telemetri verisi türü kimliği (salt okunur) Filtre alanı (?filter=) Gerekli okuma OAuth kapsamı
caloriesKcal Yakılan Aktif Enerji active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters Mesafe distance distance.interval.start_time activity_and_fitness.readonly
steps Adımlar steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute Nabız heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes Aktif Bölge Dakikası active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

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

Antrenman seansları

Günlük aktiviteleri veya antrenmanları exercise oturum veri noktaları olarak yazın. Her veri noktası, genel oturumu açıklar, etkinlik aralıklarını (duraklatma ve devam ettirme işlemleri gibi) ayrıntılı olarak belirtir ve özet metrikler (toplam mesafe, adım sayısı ve ortalama nabız gibi) sağlar.

Oturum özellikleri

Egzersiz veri noktalarını yapılandırırken aşağıdaki temel bileşenleri doğrulayın:

  • Oturum Süresi (interval): Antrenman oturumunun başlangıç ve bitiş zamanı ile bu zamanlarda geçerli olan saat dilimi farkları.
  • Etkinlik Türü (exerciseType): Gerçekleştirilen etkinliğin kategorisi (ör. RUNNING, WALKING, BIKING veya AEROBIC_WORKOUT). Fiziksel antrenmanın tam türünü belirtin.
  • Görünen Ad (displayName): Antrenman oturumu için kullanıcı dostu bir ad. REST API aracılığıyla oluşturulduğunda sunucu, exerciseType için yerelleştirilmiş görünen adı doldurur (ör. RUNNING için "Run").
  • Etkin Süre (activeDuration): Duraklatılan aralıklar hariç olmak üzere antrenmanın gerçek etkin süresi. Standart biçimlendirmede Duration biçimi kullanılır (ör. "1800s"). Sunucuda activeDuration, oturum interval değerinden exerciseEvents içindeki PAUSE/RESUME veya AUTO_PAUSE/AUTO_RESUME aralıkları çıkarılarak hesaplanır.

Özet metrikler

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

  • caloriesKcal: Antrenman sırasında yakılan toplam aktif kalori. Kilokalori (kcal) cinsinden ölçülür.
  • distanceMillimeters: Birimler arasında yüksek hassasiyet sağlamak için milimetre cinsinden ölçülen toplam mesafe.
  • steps: Egzersiz sırasında atılan toplam adım sayısı.
  • averageHeartRateBeatsPerMinute: Oturumun aktif dakikaları sırasında kullanıcının ortalama nabzı.
  • activeZoneMinutes: Antrenman sırasında kazanılan kümülatif aktif bölge dakikası.
  • averageSpeedMillimetersPerSecond: Milimetre/saniye cinsinden ortalama hareket hızı.
  • averagePaceSecondsPerMeter: Oturumun aktif dakikaları boyunca saniye/metre cinsinden ölçülen ortalama tempo.
  • elevationGainMillimeters: Oturum sırasında çıkılan toplam yükseklik.

Turlar ve bölümler

Desteklenen cihazlardan senkronize edilen ve tur içeren antrenmanlarda (ör. pistte koşu veya havuzda yüzme) splitSummaries, oturumu tura veya bölüme göre segmentlere ayırır.

Her bölme şunları içerir:

  • Belirli bir startTime ve endTime.
  • Gerçek tur süresini temsil eden bir activeDuration.
  • Yalnızca bu segment kapsamındaki 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 (manuel veya otomatik duraklatma etkinlikleri gibi) 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 ne zaman duraklatıldığını veya devam ettirildiğini gösterir.
  • AUTO_PAUSE / AUTO_RESUME: Sensör tarafından tetiklenen 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 oturumunun 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",
    "platform": "GOOGLE_WEB_API"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageHeartRateBeatsPerMinute": "148",
      "averagePaceSecondsPerMeter": 0.36
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ]
  }
}

Yanıt

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "googleWebClientId": "438076457939-example.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "metricsSummary": {
        "caloriesKcal": 380,
        "distanceMillimeters": 5000000,
        "steps": "6200",
        "averagePaceSecondsPerMeter": 0.36,
        "averageHeartRateBeatsPerMinute": "148"
      },
      "exerciseMetadata": {},
      "displayName": "Run",
      "activeDuration": "1800s",
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "updateTime": "2026-04-20T08:35:10.123456Z",
      "createTime": "2026-04-20T08:35:10.123456Z"
    }
  }
}

GPS rotaları ve konum izleme

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ı endüstri standardı 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

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

<?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 yönergelerini uygulayın.

Etkin süre ile toplam süre karşılaştırması

Hız veya tempo metriklerini hesaplamak için her zaman 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ı saat 08:00'de antrenmana başlayıp 08:35'te bitirirse antrenmanın toplam süresi 2.100 saniyedir. Kullanıcı antrenmanı 5 dakika (300 saniye) duraklattıysa ve exerciseEvents içine PAUSE ve RESUME etkinliklerini eklerseniz aktif süre "1800s" (2.100 - 300) olur. API, ortalamaları hesaplamak için etkin süreyi kullanır ve toplam mesafeyi 2.100 saniye 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 Health location kapsamını isteyin. GPS egzersizlerini incelerken uygulamanızın neden konum kapsamına ihtiyaç duyduğunu 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, rota yer paylaşımlarını oluşturmak ve GPS takibi dosyalarını (TCX) dışa aktarmak için bu iznin gerekli olduğunu açıklayın. Kullanıcı, etkinlik kapsamına izin verir ancak konum iznini reddederse exportExerciseTcx bir yetkilendirme hatası döndürür. Ancak metricsSummary üzerinden oturum toplamlarına erişmeye devam edebilirsiniz.

Webhook'ları kullanarak gerçek zamanlı senkronizasyon

Yeni antrenman verileri kullanılabilir olduğunda webhook'ları kullanarak arka ucunuzu bilgilendirmek için exercise veri türüne abone olun. Bu sayede, antrenman sonrası deneyimleri anlık olarak tetikleyebilirsiniz.

Sunucunuz bir webhook bildirimi aldığında bu bildirim, güncellenen antrenmanın healthUserId ve sivil zaman aralığını (civilIso8601TimeInterval) içerir. Sunucunuz, bildirimi 204 No Content ile hemen onaylamalı, yükü eşzamansız olarak işlemeli ve exercise.interval.civil_start_time filtresi kullanarak mutabakatı yapılmış exercise uç noktasını sorgulamalıdır (exercise'nın yalnızca civil_start_time ile filtrelemeyi desteklediğini unutmayın):

GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"

Abonelikleri ayarlama hakkında ayrıntılı bilgi için Webhook abonelikleri başlıklı makaleyi inceleyin.

Metriklerin tutarlı olmasını sağlama

Eksiksiz bir antrenman deneyimi sunmak için exercise oturumlarını yazarken özet metrikleri ekleyin ve ayrıntı grafiklerini oluştururken zaman aralığı filtrelerini kullanarak salt okunur telemetri uç noktalarını sorgulayın.

Antrenman özeti metriklerini yazma (yazma yolu)

Tamamlanmış bir antrenmanı Google Health API'ye aktarırken veya yazarken antrenmanın toplu telemetri metriklerini (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute ve averagePaceSecondsPerMeter) exercise veri noktasının metricsSummary nesnesine ekleyin:

  • POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints

Grafikler için ayrıntılı verileri sorgulama (okuma yolu)

Belirli bir seans için antrenman kontrol panelleri veya grafikleri oluşturmak istiyorsanız söz konusu antrenmanın zaman aralığı için mutabık kalınan telemetri uç noktalarını sorgulayın:

  1. interval ve metricsSummary değerlerini almak için civil_start_time filtresini kullanarak exercise uç noktasından antrenman oturumunu getirin:

    GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"

  2. Oturumun interval.startTime ve interval.endTime değerlerini kullanarak söz konusu fiziksel zaman aralığı için telemetri uç noktalarını sorgulayın.

  3. exerciseMetadata.hasGps, true ise rota koordinatlarını indirmek için exportExerciseTcx yöntemini çağırın.

Önceki
Deri sıcaklığı
Sonraki
Beslenme ve sıvı alımı