API-Spezifikationen

Der Abschnitt „API-Spezifikation“ bietet einen detaillierten Überblick über die technischen Komponenten, die für die Integration in die Plattform erforderlich sind, einschließlich Autorisierungsbereichen, Datentypdefinitionen und Endpunktstrukturen. Diese API ist eine strategische Weiterentwicklung der alten Fitbit Web API und wurde auf einer modernen Infrastruktur neu erstellt, um eine stabilere und einheitlichere Entwicklererfahrung zu bieten.

Bereiche

Sie müssen Ihre Autorisierungsanfrage aktualisieren, um die Google Health API-Bereiche zu verwenden. Die Bereiche legen fest, ob Ihre App Lese- oder Schreibvorgänge unterstützt. Folgen Sie der Anleitung zur Implementierung von Bereichen. Darin wird beschrieben, wie Sie nur die erforderlichen Bereiche anfordern, den Schreibzugriff nur beim Senden von Daten konfigurieren und eine teilweise Einwilligung ordnungsgemäß verarbeiten.

Die Google Health API-Bereiche sind eine HTTP-URL, die mit https://www.googleapis.com/auth/googlehealth.{scope} beginnt. Beispiel: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Bereichszuordnungen

So werden die Fitbit Web API-Bereiche den Google Health API-Bereichen zugeordnet:

Tabelle: Zuordnung von Fitbit Web API-Bereichen zu Google Health API-Bereichen
Fitbit Web API-Bereiche Google Health API-Bereiche
Aktivität .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
Elektrokardiogramm .ecg.readonly
Herzfrequenz .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
Standort .location.readonly
Ernährung .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
Einstellungen .settings.readonly
.settings.writeonly
Schlaf .sleep.readonly
.sleep.writeonly
Temperatur .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Gewicht .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Datentypen

Hier ist eine Liste der Google Health API-Datentypen und ihrer Zuordnung zur Fitbit Web API.

Tabelle: Zuordnung von Datentypen der Fitbit Web API zur Google Health API
Fitbit Web API-Datentyp Google Health API-Datentyp
  dataType		 Beschreibung
Aktivitätskalorien Aktiv verbrannte Energie
  active-energy-burned 		Stellt die während aktiver Phasen verbrannten Kalorien dar, einschließlich des Grundumsatzes für diese Phasen. In der Google Health API kann dies rekonstruiert werden, indem der Grundumsatz zum Datentyp active-energy-burned hinzugefügt wird, der nur den Kalorienverbrauch durch Aktivitäten ohne Grundumsatz erfasst.
Aktivzonen­minuten Aktivzonenminuten
  active-zone-minutes
Enthält Änderungen am Aktivitätsniveau des Nutzers Aktivitätsniveau
  activity-level 		Erfasst das Aktivitätsniveau des Nutzers (z. B. sitzend oder aktiv) über einen bestimmten Zeitraum.
Höhe Altitude
  altitude
Aktivität caloriesBMR Durch Grundumsatz verbrauchte Kalorien
  basal-energy-burned 		Die Kalorien, die über einen bestimmten Zeitraum durch den Grundumsatz (GU) verbrannt werden.
Blutzucker Blutzucker
  blood-glucose
Körperfett Körperfett
  body-fat
caloriesOut in jeder Herzfrequenzzone Kalorien in Herzfrequenzzone
  calories-in-heart-rate-zone
Temperatur (Kern) Körperkerntemperatur
  core-body-temperature
HFV-Zusammenfassung Tägliche Herzfrequenzvariabilität
  daily-heart-rate-variability
SpO2-Zusammenfassung Tägliche Sauerstoffsättigung
  daily-oxygen-saturation 		Eine tägliche Zusammenfassung der Statistiken zur Sauerstoffsättigung (SpO2), die anhand validierter Schlafmessungen berechnet wird.
Ruhe­herz­frequenz Tägliche Ruheherzfrequenz
  daily-resting-heart-rate
Hauttemperatur Tägliche Abweichungen der Schlaftemperatur
  daily-sleep-temperature-derivations
Entfernung Entfernung
  distance
Elektrokardiogramm (EKG) Elektrokardiogramm (EKG)
  electrocardiogram
Aufgezeichnete Aktivität Training
  exercise 		Aufgezeichnete Trainings oder Trainingseinheiten, einschließlich Start- und Endzeiten, Aktivitätstypen und Messwerten für die Trainingseinheit.
Stockwerke Stockwerke
  floors
Essen Essen
  food
Maßeinheit für Lebensmittel Maßeinheit für Lebensmittel
  food-measurement-unit
Herzfrequenz Herzfrequenz
  heart-rate
HFV im Tagesverlauf Herzfrequenzvariabilität
  heart-rate-variability
Benachrichtigungen über einen unregelmäßigen Herzrhythmus Benachrichtigung über einen unregelmäßigen Herzrhythmus
  irregular-rhythm-notification
Ernährungsprotokoll Ernährungsprotokoll
  nutrition-log
SpO2 im Tagesverlauf Sauerstoffsättigung
  oxygen-saturation 		Gibt nur validierte SpO2-Messungen auf Minutenebene zurück und schließt Messwerte aus, die aufgrund von Bewegungsartefakten oder geringer Sensorzuverlässigkeit als ungültig gekennzeichnet wurden. Da die Fitbit Web API nur den Sentinel-Wert von 50% ausgeschlossen hat, gibt die Google Health API für denselben Zeitraum weniger Datenpunkte zurück. Weitere Informationen findest du unter Sauerstoffsättigungsfilterung.
VO2max-Wert, wenn der Nutzer läuft Maximale Sauerstoffaufnahme bei Lauf
  run-vo2-max
Zeitreihe der Aktivität – Minuten im Sitzen Inaktivitätszeitraum
  sedentary-period
Schlaf Schlaf
  sleep
Schritte Schritte
  steps
Zeitreihe der Aktivität „Schwimmzüge“ Daten zu geschwommenen Bahnen
  swim-lengths-data
Aktivität caloriesOut Kalorien insgesamt
  total-calories 		Die Gesamtzahl der von einem Nutzer über einen bestimmten Zeitraum verbrannten Kalorien, einschließlich des Grundumsatzes und der verbrannten aktiven Energie.
Wert für die maximale Sauerstoffaufnahme Maximale Sauerstoffaufnahme
  vo2-max
Gewicht Gewicht
  weight

Berechnungen

Die Zuordnungen und Regeln in der Google Health API unterscheiden sich von denen in der Fitbit Web API.

Filterung der Sauerstoffsättigung

Bei der Abfrage der Sauerstoffsättigung auf Minutenebene (oxygen-saturation) wendet die Google Health API strengere Filter für die Datengültigkeit an als die alte Fitbit Web API:

  • Die alte Fitbit Web API (v1 und v3) hat nur SpO2-Proben mit einem Sentinel-Wert von 50 % ausgeschlossen.
  • Die Google Health API (v4) schließt alle SpO2-Proben aus, die vom Validierungsalgorithmus als ungültig gekennzeichnet wurden. Eine Minute wird als ungültig markiert, wenn das Signal des optischen Sensors aufgrund von Armbewegungen oder eines lockeren Sitzes am Handgelenk unzuverlässig ist, wenn der Konfidenzwert unter 50 % fällt, während der 3 Minuten unmittelbar vor und nach einem ungültigen Messwert oder wenn ein gültiger Zeitraum weniger als 4 aufeinanderfolgende Minuten dauert.

Da die Google Health API alle ungültigen Messwerte und nicht nur den 50-%-Sentinel-Wert entfernt, gibt sie für denselben Zeitraum weniger oxygen-saturation-Datenpunkte zurück als die Fitbit Web API. Es ist also mit Lücken in der minütlichen Abdeckung zu rechnen. Die zurückgegebenen Messwerte auf Minutenebene entsprechen den validierten Datenpunkten, die zur Berechnung der Schlafanalyse des Nutzers für den daily-oxygen-saturation verwendet wurden. Weitere Informationen findest du unter SpO2-Filterung und Datengültigkeit auf Minutenebene.

Aktivitätsniveau, METs und Schrittschwellenwerte

In der Google Health API wird das Aktivitätsniveau eines Nutzers pro Minute aus dem metabolischen Äquivalent (MET) und der Schrittzahl abgeleitet.

Aktivitätslevel Herzfrequenzgeräte Geräte ohne Herzfrequenzmessung
Sitzend ≤ 1,5 MET ≤ 1,5 MET
Leicht aktiv > 1,5 MET und ≤ 4,2 MET > 1,5 MET und ≤ 3,5 MET
Mäßig aktiv > 4,2 METs und < 6,0 METs
(sofern die Bedingungen für Sehr aktiv nicht erfüllt sind)		 > 3,5 METs und < 6,0 METs
(sofern die Bedingungen für Sehr aktiv nicht erfüllt sind)
Sehr aktiv ≥ 6,0 METs oder ≥ 5,0 METs mit einer Schrittfrequenz von mindestens 150 Schritten pro Minute ≥ 6,0 METs oder ≥ 5,0 METs mit einer Schrittfrequenz von mindestens 150 Schritten pro Minute

Aktive Minuten bestehen aus kombinierten MODERATELY_ACTIVE- und VERY_ACTIVE-Minuten. Eine Minute mit hoher Aktivität wird jedoch nur dann als Aktive Minute angerechnet, wenn sie während einer kontinuierlichen Aktivität von mindestens 10 Minuten auftritt, wobei höchstens 2 Minuten mit geringerer Aktivität zulässig sind.

Minuten im Sitzen und Schlaf

Die Schlafzeit wird nicht zu den Minuten ohne Bewegung gezählt. In täglichen Zusammenfassungen werden die Minuten ohne Aktivität berechnet, indem die Schlafminuten und die aktiven Minuten (leicht aktiv, mäßig aktiv und sehr aktiv) von den Gesamtminuten des Tages (1.440 Minuten) abgezogen werden:

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

Body-Mass-Index (BMI)

Da die Google Health API keinen integrierten BMI-Datentyp bereitstellt, müssen Anwendungen den Body-Mass-Index clientseitig anhand von Größen- und Gewichtsdaten berechnen:

  1. Rufe das Gewicht des Nutzers in Gramm aus dem Feld weightGrams im Datentyp Gewicht ab. Rechnen Sie diesen Wert in Kilogramm (durch 1.000 teilen) oder Pfund (durch 453,59237 teilen) um.
  2. Rufe die Größe des Nutzers in Millimetern aus dem Feld heightMillimeters im Datentyp Größe ab. Rechnen Sie diesen Wert in Meter (durch 1.000 teilen) oder Zoll (durch 25,4 teilen) um.
  3. Verwenden Sie eine der folgenden Formeln, um den BMI-Wert zu berechnen:
    • Messwertformel: BMI = weight (kg) / [height (m)]^2
    • Formel für imperiale Einheiten: BMI = (weight (lbs) / [height (in)]^2) * 703

Die resultierenden BMI-Werte entsprechen den folgenden Kategorien:

Gewichtskategorie BMI-Bereich
Untergewicht Unter 18,5
Gesundes Gewicht 18,5 bis 24,9
Übergewicht 25 bis 29,9
Adipös 30 oder höher

Grundumsatz (GU)

Der Grundumsatz ist die Mindestanzahl an Kalorien, die für die grundlegenden Körperfunktionen im Ruhezustand erforderlich sind. Da die Google Health API keinen integrierten BMR-Datentyp bereitstellt, müssen Anwendungen ihn clientseitig mithilfe der Harris-Benedict-Formel berechnen. Weitere Informationen findest du im Wikipedia-Artikel zur Harris-Benedict-Formel.

So führen Sie diese Berechnung durch:

  1. Rufe das Gewicht des Nutzers in Gramm aus dem Feld weightGrams im Datentyp Gewicht ab und rechne es in Kilogramm um (durch 1.000 teilen). Wenn Sie Pfund in Kilogramm umrechnen möchten, teilen Sie den Wert durch 2,2.
  2. Rufe die Größe des Nutzers in Millimetern aus dem Feld heightMillimeters im Datentyp Größe ab und rechne sie in Zentimeter um (durch 10 teilen). Wenn Sie Zoll in Zentimeter umrechnen möchten, multiplizieren Sie den Wert mit 2,54.
  3. Rufen Sie das Alter des Nutzers in Jahren aus dem Feld age in der Ressource Profile ab.
  4. Rufe das biologische Geschlecht unabhängig ab (z. B. indem du den Nutzer aufforderst, es anzugeben, oder es in deiner eigenen Datenbank speicherst), da die Google Health API dieses Feld nicht bereitstellt.
  5. Verwenden Sie eine der folgenden Formeln, die auf dem biologischen Geschlecht des Nutzers basieren:
    • Männer: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Frauen: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Täglicher Gesamtenergieverbrauch (TDEE)

Der tägliche Gesamtenergieverbrauch (TDEE) ist eine Schätzung der Gesamtzahl der Kalorien, die eine Person an einem Tag verbrennt. Dabei werden sowohl der Grundumsatz als auch die körperliche Aktivität berücksichtigt. Um den TDEE des Nutzers zu schätzen, multipliziere den BMR-Wert mit einem Aktivitätsfaktor, der seinem Lebensstil entspricht:

Aktivitätslevel Beschreibung Multiplikator
Sitzend Wenig oder kein Sport. BMR x 1.2
Leicht aktiv 1–3 Trainingstage pro Woche. BMR x 1.375
Mäßig aktiv 3–5 Trainingstage pro Woche. BMR x 1.55
Sehr aktiv 6–7 Trainingstage pro Woche. BMR x 1.725
Besonders aktiv Sehr anstrengendes Training oder körperliche Arbeit. BMR x 1.9

Endpunkte

Die REST-Endpunkte verwenden für alle Datentypen eine einheitliche Syntax.

  • Dienstendpunkt: Die HTTP-URL-Basis ändert sich in https://health.googleapis.com.
  • Endpunktsyntax: Die Google Health API unterstützt eine begrenzte Anzahl von Endpunkten, die von den meisten unterstützten Datentypen verwendet werden können. Dies bietet eine einheitliche Syntax für alle Datentypen und erleichtert die Verwendung der Endpunkte.
  • Nutzer-ID: In der Endpunktsyntax muss entweder die Nutzer-ID oder „me“ angegeben werden. Wenn Sie „me“ verwenden, wird die Nutzer-ID aus dem Zugriffstoken abgeleitet.

Beispiel: Hier ist ein Beispiel für den Endpunkt „GET Profile“, der über die Google Health API aufgerufen wird.

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

Endpunktzuordnungen

Eine Liste der verfügbaren Datentypen und der von ihnen unterstützten API-Methoden finden Sie in der Tabelle Google Health API-Datentypen.

Fitbit Web API-Endpunkttyp Google Health API
GET (Log | Summary | Daily Summary), wobei Sie Daten für einen einzelnen Tag anfordern dailyRollup-Methode mit windowSize = 1 Tag
GET (Intraday), wenn du detaillierte Daten anforderst Methode list
GET (Zeitreihe) nach Datum oder Intervall Methode rollUp oder dailyRollUp mit einem Zeitraum
GET (Logliste) Methode list
CREATE- und UPDATE-Logs Methode patch
DELETE-Logs Methode batchDelete
GET-Profil users.getProfile gibt die spezifischen Informationen des Nutzers zurück
users.getSettings gibt die Einheiten und Zeitzonen des Nutzers zurück
Profil aktualisieren users.updateProfile ändert die spezifischen Informationen des Nutzers
users.updateSettings ändert die Einheiten und Zeitzonen des Nutzers
Nutzer-ID abrufen users.getIdentity gibt die Fitbit-Legacy- und Google-Nutzer-ID des Nutzers zurück.
Geräte abrufen users.pairedDevices gibt die Liste der gekoppelten Geräte zurück.
Abos erstellen projects.subscribers.subscriptions.create erstellt manuell ein Abo
Abos löschen projects.subscribers.subscriptions.delete – Abo löschen
Aboliste abrufen projects.subscribers.subscriptions.list listet alle Abos auf.