API spesifikasyonları

API Spesifikasyonu bölümünde, platformla entegrasyon için gerekli olan teknik bileşenlere (ör. yetkilendirme kapsamları, veri türü tanımları ve uç nokta yapıları) dair ayrıntılı bir genel bakış sunulur. Bu API, eski Fitbit Web API'nin stratejik bir evrimini temsil eder. Daha kararlı ve tutarlı bir geliştirici deneyimi sağlamak için modern altyapı üzerinde yeniden oluşturulmuştur.

Kapsamlar

Google Health API kapsamlarını kullanmak için yetkilendirme isteğinizi güncellemeniz gerekir. Kapsamlar, uygulamanızın okuma veya yazma işlemlerini destekleyip desteklemediğini tanımlar. Yalnızca gerekli kapsamları istemeyi, yazma erişimini yalnızca veri gönderirken yapılandırmayı ve kısmi izni düzgün bir şekilde işlemeyi belirten kapsam uygulama talimatlarını uygulayın.

Google Health API kapsamları, https://www.googleapis.com/auth/googlehealth.{scope} ile başlayan bir HTTP URL'sidir. Örneğin, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Kapsam eşlemeleri

Fitbit Web API kapsamları, Google Health API kapsamlarıyla şu şekilde eşleşir:

Tablo: Fitbit Web API'den Google Health API'ye kapsam eşlemeleri
Fitbit Web API kapsamları Google Health API kapsamları
etkinlik .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
elektrokardiyogram .ecg.readonly
nabız .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
konum .location.readonly
beslenme .nutrition.readonly
.nutrition.writeonly
oxygen_saturation : .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
profil .profile.readonly
.profile.writeonly
respiratory_rate : .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
ayarlar .settings.readonly
.settings.writeonly
uyku .sleep.readonly
.sleep.writeonly
sıcaklık : .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
ağırlık .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Veri türleri

Google Health API veri türlerinin listesini ve Fitbit Web API ile nasıl eşleştiklerini aşağıda bulabilirsiniz.

Tablo: Fitbit Web API'den Google Health API'ye veri türü eşlemeleri
Fitbit Web API Veri Türü Google Health API Veri Türü
  dataType		 Açıklama
Aktivite Kalorisi Aktif Enerji Yakımı
  active-energy-burned 		Aktif dönemlerde yakılan kalorileri (bu dönemlerdeki BMR dahil) temsil eder. Google Health API'de bu, BMR'yi active-energy-burned veri türüne (bazal hızı hariç tutarak yalnızca aktiviteyi izler) ekleyerek yeniden oluşturulabilir.
Aktif Bölge Dakikası Aktif Bölge Dakikası
  active-zone-minutes
Kullanıcının etkinlik düzeylerindeki değişiklikleri içerir. Etkinlik Düzeyi
  activity-level 		Kullanıcının belirli bir süre boyunca aktivite düzeyini (ör. hareketsiz veya aktif) yakalar.
Rakım Altitude
  altitude
Etkinlik caloriesBMR Harcanan Bazal Enerji
  basal-energy-burned 		Belirli bir süre boyunca bazal metabolizma hızı (BMR) nedeniyle yakılan kalori miktarı.
Kan Şekeri Kan Şekeri
  blood-glucose
Vücut yağ yüzdesi Vücut Yağ Yüzdesi
  body-fat
Her nabız bölgesinde caloriesOut Nabız Bölgesindeki Kalori
  calories-in-heart-rate-zone
Sıcaklık (Çekirdek) Çekirdek Vücut Sıcaklığı
  core-body-temperature
HRV özeti Günlük Nabız Değişkenliği
  daily-heart-rate-variability
SpO2 özeti Günlük Oksijen Doygunluğu
  daily-oxygen-saturation 		Doğrulanmış uyku ölçümlerinden hesaplanan kan oksijen doygunluğu (SpO2) istatistiklerinin günlük özeti.
Dinlenme nabzı Günlük Dinlenme Nabzı
  daily-resting-heart-rate
Deri sıcaklığı Günlük Uyku Sıcaklığı Değişimleri
  daily-sleep-temperature-derivations
Mesafe Mesafe
  distance
Elektrokardiyogram (EKG) Elektrokardiyogram (EKG)
  electrocardiogram
Kaydedilen etkinlik Egzersiz
  exercise 		Başlangıç/bitiş zamanları, aktivite türleri ve seans metriklerini içeren kayıtlı antrenmanlar veya egzersiz seansları.
Döşeme Katlar
  floors
Yiyecekler Yiyecek
  food
Gıda Ölçü Birimi Yiyecek Ölçü Birimi
  food-measurement-unit
Nabız Nabız
  heart-rate
Gün içi HRV Nabız Değişkenliği
  heart-rate-variability
Düzensiz Kalp Ritmi Bildirimleri (IRN) Düzensiz Kalp Ritmi Bildirimi
  irregular-rhythm-notification
Yemek Günlüğü Beslenme Günlüğü
  nutrition-log
SpO2 Gün İçi Oksijen Doygunluğu
  oxygen-saturation 		Yalnızca doğrulanmış dakika düzeyinde SpO2 ölçümlerini döndürür ve hareket kusurları veya düşük sensör güvenilirliği nedeniyle geçersiz olarak işaretlenen ölçümleri hariç tutar. Fitbit Web API yalnızca %50'lik sentinel değerini hariç tuttuğu için Google Health API aynı zaman aralığı için daha az veri noktası döndürür. Ayrıntılar için Oksijen doygunluğu filtreleme bölümüne bakın.
Kullanıcı koşarken maksimum oksijen tüketimi değeri Koşuda Maks. Oksijen Tüketimi
  run-vo2-max
Aktivite zaman serisi hareketsiz dakika sayısı Hareketsiz Dönem
  sedentary-period
Uyku Uyku
  sleep
Adımlar Adımlar
  steps
Etkinlik zaman serisi yüzme kulaçları Yüzülen Kulvar Verileri
  swim-lengths-data
Etkinlik caloriesOut Toplam Kalori
  total-calories 		Bazal metabolizma hızı ve yakılan aktif enerji dahil olmak üzere bir kullanıcının belirli bir süre boyunca yaktığı toplam kalori miktarı.
Maksimum oksijen tüketimi değeri Maksimum oksijen tüketimi
  vo2-max
Ağırlık Ağırlık
  weight

Hesaplamalar

Google Health API'deki eşlemeler ve kurallar, Fitbit Web API'den farklıdır.

Oksijen doygunluğu filtreleme

Google Health API, dakika düzeyinde kan oksijen doygunluğu (oxygen-saturation) sorgulaması yaparken eski Fitbit Web API'ye kıyasla daha katı veri geçerliliği filtrelemesi uygular:

  • Eski Fitbit Web API (v1 ve v3) yalnızca %50'lik bir sentinel değerine sahip SpO2 örneklerini hariç tutuyordu.
  • Google Health API (v4), doğrulama algoritması tarafından geçersiz olarak işaretlenen tüm SpO2 örneklerini hariç tutar. Kol hareketi veya bilekliğin gevşek olması nedeniyle optik sensör sinyali güvenilir olmadığında, güven puanı %50'nin altına düştüğünde, geçersiz bir ölçümden hemen önceki ve sonraki 3 dakika içinde veya geçerli bir ölçüm süresi art arda 4 dakikadan kısa sürdüğünde bir dakika geçersiz olarak işaretlenir.

Google Health API, yalnızca %50 nöbetçi değerini değil, tüm geçersiz ölçümleri kaldırdığı için aynı zaman aralığında Fitbit Web API'den daha az oxygen-saturation veri noktası döndürür ve dakika dakika kapsamda boşluklar olması beklenir. Döndürülen dakika düzeyindeki ölçümler, kullanıcının daily-oxygen-saturation uyku özetini hesaplamak için kullanılan doğrulanmış veri noktalarıyla uyumludur. Daha fazla bilgi için Dakika düzeyinde SpO2 filtreleme ve veri geçerliliği başlıklı makaleyi inceleyin.

Etkinlik düzeyi, MET'ler ve adım eşikleri

Google Health API'de, kullanıcının dakika bazında etkinlik düzeyi, metabolik eş değer (MET) ve adım sayısından türetilir.

Etkinlik düzeyi Nabız ölçüm cihazları Nabız ölçmeyen cihazlar
Hareketsiz ≤ 1,5 MET ≤ 1,5 MET
Hafif Aktif > 1,5 MET ve ≤ 4,2 MET 1,5 MET'ten fazla ve 3,5 MET'ten az veya 3,5 MET'e eşit
Orta Düzeyde Aktif > 4,2 MET ve < 6,0 MET
(Çok Aktif koşulları karşılanmadığı sürece)		 > 3,5 MET ve < 6,0 MET
(Çok Aktif koşulları karşılanmadığı sürece)
Çok Etkin ≥ 6,0 MET veya ≥ 5,0 MET (dakikada 150 adım veya daha fazla adım hızıyla) ≥ 6,0 MET veya ≥ 5,0 MET (dakikada 150 adım veya daha fazla adım hızıyla)

Aktif dakikalar, MODERATELY_ACTIVE ve VERY_ACTIVE dakikalarının toplamından oluşur. Ancak yüksek düzeyde aktif dakikalar, yalnızca en az 10 dakikalık kesintisiz bir süre boyunca gerçekleşirse ve daha düşük aktivite için en fazla 2 dakikalık boşluklara izin verilirse sayılır.

Hareketsiz geçirilen süre ve uyku

Hareketsiz geçirilen dakikalara uyku süresi dahil değildir. Günlük özetlerde hareketsiz dakikalar, uyku dakikaları ve aktif dakikaların (hafif aktif, orta derecede aktif ve çok aktif) gün içindeki toplam dakikadan (1.440 dakika) çıkarılmasıyla hesaplanır:

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

Vücut Kitle İndeksi (VKİ)

Google Health API, yerleşik bir BMI veri türü sunmadığından uygulamaların, boy ve kilo kayıtlarını kullanarak istemci tarafında vücut kitle indeksini hesaplaması gerekir:

  1. Ağırlık veri türündeki weightGrams alanından kullanıcının gram cinsinden ağırlığını alın. Bu değeri kilograma (1.000'e bölün) veya pound'a (453,59237'ye bölün) dönüştürün.
  2. Kullanıcının boyunu milimetre cinsinden Boy veri türündeki heightMillimeters alanından alın. Bunu metreye (1.000'e bölün) veya inçe (25,4'e bölün) dönüştürün.
  3. VKİ değerini hesaplamak için aşağıdaki formüllerden birini kullanın:
    • Metrik formülü: BMI = weight (kg) / [height (m)]^2
    • İngiliz ölçü birimi formülü: BMI = (weight (lbs) / [height (in)]^2) * 703

Elde edilen BMI değerleri aşağıdaki kategorilere karşılık gelir:

Ağırlık kategorisi VKİ aralığı
Düşük kilolu 18,5'in altında
Sağlıklı kilo 18,5-24,9
Fazla kilolu 25-29,9
Obez 30 veya daha yüksek

Bazal metabolizma hızı (BMR)

Bazal metabolizma hızı (BMR), dinlenme halindeyken temel vücut işlevleri için gereken minimum kalori miktarıdır. Google Health API, yerleşik bir BMR veri türü sunmadığından uygulamaların bu değeri Harris-Benedict formülünü kullanarak istemci tarafında hesaplaması gerekir. Daha fazla bilgi edinmek için Wikipedia'daki Harris-Benedict denklemi makalesine göz atın.

Bu hesaplamayı yapmak için:

  1. Ağırlık veri türündeki weightGrams alanından kullanıcının gram cinsinden ağırlığını alın ve kilograma dönüştürün (1.000'e bölün). Pound'u kilograma dönüştürmek için 2, 2'ye bölün.
  2. Boy veri türündeki heightMillimeters alanından kullanıcının boyunu milimetre cinsinden alın ve santimetreye dönüştürün (10'a bölün). İnçleri santimetreye dönüştürmek için 2, 54 ile çarpın.
  3. Profile kaynağındaki age alanından kullanıcının yaşını yıl olarak alın.
  4. Google Health API bu alanı göstermediğinden biyolojik cinsiyeti bağımsız olarak alın (örneğin, kullanıcıdan isteyerek veya kendi veritabanınızda tutarak).
  5. Kullanıcının biyolojik cinsiyetine göre aşağıdaki formüllerden birini kullanın:
    • Erkek: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Kadın: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Toplam Günlük Enerji Tüketimi (TGET)

Toplam Günlük Enerji Tüketimi (TDEE), bir kişinin bir günde yaktığı toplam kalori miktarının tahminidir. Bu tahminde hem BMR hem de fiziksel aktivite dikkate alınır. Kullanıcının TDEE'sini tahmin etmek için BMR değerini, yaşam tarzına karşılık gelen bir aktivite faktörüyle çarpın:

Etkinlik düzeyi Açıklama Çarpan
Hareketsiz Az egzersiz yapıyorsunuz veya hiç yapmıyorsunuz. BMR x 1.2
Hafif aktif Haftada 1-3 gün egzersiz yapıyorsanız BMR x 1.375
Orta düzeyde aktif Haftada 3-5 gün egzersiz yapın. BMR x 1.55
Çok aktif Haftada 6-7 gün egzersiz yapma BMR x 1.725
Çok aktif Çok ağır egzersiz veya fiziksel iş. BMR x 1.9

Uç noktalar

REST uç noktaları, tüm veri türleri için tutarlı bir söz dizimi kullanır.

  • Hizmet uç noktası: Temel HTTP URL'si https://health.googleapis.com olarak değişir.
  • Uç Nokta Söz Dizimi: Google Health API, desteklenen veri türlerinin çoğu tarafından kullanılabilen sınırlı sayıda uç noktayı destekler. Bu sayede tüm veri türleri için tutarlı bir söz dizimi sağlanır ve uç noktaların kullanımı kolaylaşır.
  • Kullanıcı Tanımlayıcısı: Uç nokta söz diziminde kullanıcı kimliği veya "me" belirtilmelidir. Beni kullanırken kullanıcı kimliği, erişim jetonundan alınır.

Örnek: Google Health API kullanılarak çağrılan GET Profile uç noktası örneğini aşağıda bulabilirsiniz.

GET https://health.googleapis.com/v4/users/me/profile

Uç nokta eşlemeleri

Kullanılabilir veri türlerinin ve destekledikleri API yöntemlerinin listesi için Google Health API veri türleri tablosuna bakın.

Fitbit Web API Uç Noktası Türü Google Health API
Tek bir güne ait verileri istediğiniz GET (Log | Summary | Daily Summary) windowSizeDays: 1 ile dailyRollUp yöntemi (POST .../dataPoints:dailyRollUp)
Ayrıntılı veri istediğiniz GET (Gün içi) list yöntemi
Tarihe veya aralığa göre GET (Zaman Serisi) Tarih aralığı içeren rollUp veya dailyRollUp yöntemi
GET (Günlük Listesi) list yöntemi
CREATE ve UPDATE günlükleri patch yöntemi
DELETE Günlükleri batchDelete yöntemi
GET Profile users.getProfile kullanıcının belirli bilgilerini döndürür
users.getSettings kullanıcının birimlerini ve saat dilimlerini döndürür
Profili güncelleme users.updateProfile, kullanıcının belirli bilgilerini değiştirir
users.updateSettings, kullanıcının birimlerini ve saat dilimlerini değiştirir
Kullanıcı kimliğini alma users.getIdentity, kullanıcının eski Fitbit ve Google kullanıcı kimliğini döndürür.
Cihazları Al users.pairedDevices, eşlenen cihazların listesini döndürür.
Abonelik oluşturma projects.subscribers.subscriptions.create manuel olarak abonelik oluşturduğunda
Abonelikleri silme projects.subscribers.subscriptions.delete aboneliği silme
Abonelik Listesini Al projects.subscribers.subscriptions.list tüm abonelikleri listeler