Endpunkte

Auf dieser Seite finden Sie einen Überblick über die REST API-Konventionen sowie einen Index der häufigsten Google Health API-Aufgaben und Beispiele für jede Aufgabe.

REST API-Konventionen

Die Google Health API entspricht den Google API Improvement Proposals (AIP), insbesondere AIP-127 (HTTP- und gRPC-Transcodierung) und AIP-131 bis AIP-135 (Standardmethoden). Diese Standards definieren, wie Daten aus einer Proto-Nachricht einer HTTP-Anfrage zugeordnet werden.

Suchparameter

Abfrageparameter werden verwendet, wenn die Daten Teil der URL sind. Dies gilt in erster Linie für GET-Anfragen (Abrufen einer Ressource) oder LIST-Anfragen (Filtern/Paginierung), wird aber auch für DELETE-Vorgänge verwendet.

  • Placement: Wird nach einem ? an die URL angehängt.
  • Syntax: Schlüssel/Wert-Paare, die durch & getrennt sind.
  • Zuordnung: Jedes Feld in der Anfragenachricht, das nicht Teil der URL-Pfadvorlage ist, wird einem Suchparameter zugeordnet.
  • Am besten geeignet für: Einfache Typen (Strings, Ganzzahlen, Enumerationen) und wiederkehrende Felder.

Beispielsyntax:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

Anfragetext

Der Anfragetext wird verwendet, wenn die Daten den Status einer Ressource ändern oder zu groß für eine URL sind. Der Text ist in der Regel eine JSON-Darstellung der Ressource selbst. Wird in der Regel für die Vorgänge POST, PATCH und PUT verwendet.

  • Platzierung: Innerhalb der HTTP-Nutzlast (nicht in der URL sichtbar).
  • Syntax: Als JSON-Objekt formatiert.
  • Zuordnung: In der google.api.http-Annotation definiert.
    • body: "*" bedeutet, dass die gesamte Nachricht der Text ist.
    • body: "resource_name" bedeutet, dass nur ein bestimmtes Feld im Proto der Textkörper ist.
  • Am besten geeignet für: Komplexe Objekte, verschachtelte Nachrichten und vertrauliche Daten.

Beispielsyntax:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

Der Hybridfall

In einer AIP-134-kompatiblen Update-Methode oder einem PATCH-Vorgang werden beide verwendet. Die URL enthält den Ressourcennamen, der Text enthält die aktualisierten Ressourcendaten und ein Abfrageparameter (in der Regel update_mask) gibt an, welche Felder geändert werden sollen.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

Wichtige Unterschiede auf einen Blick

Funktion Suchparameter Anfragetext
AIP-Anleitung Wird für Such-, Filter- und Lesevorgänge verwendet. Wird für Schreibvorgänge verwendet.
Sichtbarkeit Sichtbar im Browserverlauf und in Serverlogs. Die URL ist nicht sichtbar.
Komplexität Beschränkt auf flache oder wiederkehrende Strukturen. Unterstützt tief verschachtelte JSON-Objekte.
Encoding Muss URL-codiert sein (z. B. werden Leerzeichen zu %20). Standard-JSON-Codierung.

Daten

Alle Datumsangaben in der Google Health API werden im Format YYYY-MM-DD angezeigt. Die Nutrition API unterstützt den ISO 8601-Standard für Datumswerte unter den folgenden Bedingungen:

  • Eine vierstellige Jahreszahl YYYY
  • Jahreswerte im Bereich von 0000 bis 9999
  • Keine Durchsetzung von Startdatumsbeschränkungen, die durch den ISO 8601-Standard oder eine andere Epoche impliziert werden

Header

Für die Ausführung der Google Health API-Endpunkte sind die entsprechenden Header und das Zugriffstoken erforderlich. Der folgende Header wird sowohl für GET- als auch für POST-Anfragen empfohlen:

Authorization: Bearer access-token
Accept: application/json

API-Aufgabenindex

In diesem Abschnitt finden Sie einen Index mit gängigen Google Health API-Aufgaben und Beispielen für jede Aufgabe.

Fitbit- oder Google-Nutzer-ID abrufen

Nachdem ein Nutzer über Google OAuth 2.0 zugestimmt hat, enthält die Tokenantwort nicht die Fitbit- oder Google-Nutzer-ID. Rufen Sie den Endpunkt getIdentity auf, um die Nutzer-ID zu erhalten. getIdentity gibt sowohl die alte Fitbit-Nutzer-ID als auch die Google-Nutzer-ID zurück.

Wir empfehlen, dass Sie den getIdentity-Endpunkt aufrufen und beide Nutzer-IDs speichern, sobald ein neuer Nutzer über OAuth seine Einwilligung erteilt. Dadurch wird die Abwärts- und Aufwärtskompatibilität Ihrer Integration gewährleistet.

Beispiel:

Anfrage

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

Daten zum Tagesverlauf oder detaillierte Daten abrufen, die über den Tag hinweg erhoben wurden

Verwenden Sie den list-Endpunkt für einen bestimmten Datentyp, um tagesinterne oder detaillierte Daten abzurufen, die im Laufe des Tages in unterstützten Intervallen für diesen Datentyp erfasst wurden.

Beispiel:

Anfrage

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

Abgestimmte Ansicht von Intervall-Daten abrufen

Wenn Sie Intervalldaten ohne sich überschneidende Datensätze oder Konflikte für verschiedene Geräte abrufen möchten, rufen Sie den reconcile-Endpunkt auf. Der Abgleichsendpunkt dedupliziert automatisch sich überschneidende Intervalle über Synchronisierungsbatches und mehrere Aufzeichnungsgeräte hinweg und gibt einen autoritativen, kontinuierlichen Stream zurück, der sich für das Rendern von Aktivitätszeitachsen und das Berechnen von Zeiträumen eignet.

Hintergrundinformationen dazu, warum verbundene Geräte sich überschneidende Intervalle erzeugen, und ein betrieblicher Vergleich zwischen list und reconcile finden Sie im Leitfaden zur Datenverwaltung.

Im folgenden Beispiel wird die Antwort von list (die beide sich überschneidenden Datensätze zurückgibt) mit der Antwort von reconcile (die den Konflikt durch Zurückgeben des autoritativen Datensatzes löst) für einen Nutzer mit zwei sich überschneidenden Trainingseinheiten verglichen:

Rohliste

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Abgeglichen

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Bei der Abstimmung werden widersprüchliche Sitzungen aufgelöst, indem Duplikate entfernt und der maßgebliche Datensatz ausgewählt wird, anstatt eine künstliche Zeitvereinigung zu erstellen (z. B. 11:00:00Z bis 11:50:00Z). Bei der abgestimmten Antwort wird der beste Datenpunkt (7797422996486764704) mit dem ursprünglich aufgezeichneten Intervall (11:20:00Z bis 11:50:00Z) zurückgegeben. So wird die Integrität der gemessenen Telemetrie und Messwerte dieser Sitzung gewahrt.

Daten filtern

Wenn Sie bestimmte Teilmengen von Datenpunkt-Datensätzen abrufen möchten, die Kriterien wie ein Zeitintervall, ein Datum oder eine Beobachtungszeit erfüllen, verwenden Sie den Endpunkt list oder reconcile mit dem Parameter filter.

Ausführliche Richtlinien, Formatierungsregeln, Validierungsfehler und Beispielabfragen finden Sie im Leitfaden zum Filtern von Daten.

Nach Datenquellenfamilie filtern

Wenn Sie Daten aus bestimmten Quelltypen isolieren oder zusammenfassen möchten (z. B. physische Wearables im Vergleich zu manuellen Einträgen), verwenden Sie den Parameter dataSourceFamily.

Detaillierte Richtlinien, unterstützte Familien sowie Anfrage- und Antwortbeispiele für reconcile, rollUp und dailyRollUp finden Sie im Leitfaden zum Filtern von Daten unter Nach Datenquellenfamilie filtern.

Daten nach dem zivilen Startzeitpunkt eines Intervalls filtern

Verwenden Sie den list-Endpunkt mit dem Parameter filter, um Daten nach bürgerlicher Zeit oder einem Intervall zu filtern.

Beispiel:

Anfrage

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

Daten nach der physischen Zeit einer Stichprobenbeobachtung filtern

Verwenden Sie den Endpunkt list mit dem Parameter filter, um Daten nach der physischen Zeit der Stichprobenbeobachtung zu filtern.

Beispiel:

Anfrage

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

Nach Datenquellenfamilie filtern und aggregieren

Eine Datenquellenfamilie ist eine logische Gruppierung von Datenquellen wie Smartwatches, mobilen Apps oder manuellen Einträgen. So können Sie Daten aus bestimmten Quelltypen isolieren oder zusammenfassen (z. B. physische Wearables im Vergleich zu manuellen Einträgen).

Die Endpunkte reconcile, rollUp und dailyRollUp unterstützen alle den Parameter dataSourceFamily. Der Übergabemechanismus hängt vom Endpunkt ab:

Endpunkt (HTTP-Methode) Mechanismus
reconcile (GET) Übergeben Sie dataSourceFamily als URL-Suchparameter.
rollUp (POST) Übergeben Sie dataSourceFamily als Feld im JSON-Anfragetext.
dailyRollUp (POST) Übergeben Sie dataSourceFamily als Feld im JSON-Anfragetext.

Unterstützte Datenquellenfamilien

In der folgenden Tabelle werden die unterstützten dataSourceFamily-Werte beschrieben:

Option Beschreibung
users/me/dataSourceFamilies/all-sources Standardwert: Gibt Datenpunkte zurück, die über alle registrierten Datenquellen für selbst erhobene Daten und Drittanbieterdaten hinweg abgeglichen wurden. Mit dieser Option werden Daten aus Drittanbieter-Apps zurückgegeben, z. B. Schritte von der Smartwatch, Schritte aus Drittanbieter-Apps, Schritte vom Smartphone und manuell eingegebene Schritte.
users/me/dataSourceFamilies/google-wearables Enthält Daten, die von Google- und Fitbit-Trackern (z. B. Fitbit-Wearables und Pixel Watch) aufgezeichnet wurden. Schließt manuell erfasste Daten und vom Smartphone geschätzte Daten aus. Verwenden Sie diese Option, wenn für Ihre Integration Rohdaten der Sensoren erforderlich sind, die direkt von der Wearable-Hardware aufgezeichnet werden.
users/me/dataSourceFamilies/google-sources Beinhaltet selbst erhobene Daten von Google und Fitbit. Dazu gehören Aufzeichnungen von physischen Trackergeräten, Daten von Health Connect und alle manuellen Einträge, die über Erstanbieter-Apps wie die Fitbit App oder Google Fit protokolliert wurden.

Wenn Sie einen abgeglichenen Datenstream aus einer bestimmten Datenquellenfamilie abrufen möchten, rufen Sie den reconcile-Endpunkt mit dem Abfrageparameter dataSourceFamily auf.

Mit der folgenden GET-Anfrage werden beispielsweise die vom Tracker aufgezeichneten Schlafdaten für den Tag nach dem 03.03.2026 abgerufen:

Anfrage

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

Wenn Sie Datenpunkte über eine bestimmte Fenstergröße hinweg aggregieren möchten, die auf eine bestimmte Datenquellenfamilie beschränkt ist, rufen Sie den Endpunkt rollUp auf und übergeben Sie das Feld dataSourceFamily im JSON-Anfragetext.

Mit der folgenden POST-Anfrage werden die Anzahl der Schritte pro Stunde (3600s) abgefragt, die ausschließlich von Wearables erfasst wurden:

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

Antwort

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

Wenn Sie tägliche Datenpunkte für eine bestimmte Quellenfamilie zusammenfassen möchten, rufen Sie den Endpunkt dailyRollUp auf und übergeben Sie das Feld dataSourceFamily im Anfragetext.

Mit der folgenden Anfrage werden beispielsweise die täglichen Zusammenfassungen für die Schritte des Nutzers berechnet, einschließlich aller Google- und Fitbit-Quellen von Erstanbietern (Wearables + manuelle Einträge):

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

Antwort

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

Datenpunkte über einen bestimmten Zeitraum hinweg zusammenfassen

Verwenden Sie den rollUp-Endpunkt, um die Summe der Datenpunkte basierend auf einem Zeitfenster in Sekunden über den datetime-Bereich basierend auf der physischen Zeit des Nutzers (in UTC) zurückzugeben.

Geben Sie beim Aufrufen des Endpunkts rollUp den Anfragetext an, der den erforderlichen Zeitraum und windowSize darstellt. Beachten Sie die folgenden Anforderungen für windowSize:

  • Mindestzeitraum: Die Dauer windowSize muss mindestens 1 Sekunde betragen ("1s"). Zeiträume mit einer Dauer von weniger als einer Sekunde, mit einer Dauer von null oder mit einer negativen Dauer werden mit dem Fehler 400 Bad Request (INVALID_ROLLUP_WINDOW) abgelehnt.
  • Ausrichtung der Speicherauflösung: Um eine ungleichmäßige Verteilung der aggregierten Daten auf die Unter-Buckets zu vermeiden, wählen Sie eine windowSize aus, die gleich oder größer als die zugrunde liegende Speicherauflösung des Datentyps ist (z. B. "60s" für 1-Minuten-Schrittintervalle). Weitere Informationen finden Sie unter Größe des Rollup-Fensters und zugrunde liegende Speicherauflösung.

Wenn Sie beispielsweise die Schrittanzahl in 1-Minuten-Intervallen (60s) zusammenfassen möchten:

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-02-17T17:00:00Z",
    "endTime": "2026-02-17T17:59:59Z"
  },
  "windowSize": "60s"
}

Antwort

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:56:00Z",
      "steps": {
        "countSum": "72"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:55:00Z",
      "steps": {
        "countSum": "85"
      }
    },
...
  ]
}

Daten für einen oder mehrere Tage zusammenfassen

Der dailyRollUp-Endpunkt sollte verwendet werden, wenn Sie Daten für einen einzelnen Tag oder mehrere Tage, auch windowSize genannt, zusammenfassen möchten. Geben Sie im Anfragetext den geschlossenen/offenen zivilen Zeitbereich für das erforderliche Intervall an. Je nach Datentyp erhalten Sie entweder die Summe oder den Durchschnitt über das Intervall.

Beispiel:

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 23,
        "minutes": 59,
        "seconds": 59,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1
}

Antwort

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "3822"
      }
    }
  ]
}

Bucketing, wenn der Bereich kein Vielfaches der Fenstergröße ist

Wenn der angeforderte Bereich kein genaues Vielfaches von windowSize (oder windowSizeDays) ist, wird der letzte Bucket chronologisch am oberen Endpunkt des Bereichs abgeschnitten und umfasst einen Zeitraum, der kürzer als die Fenstergröße ist. Die API akzeptiert Ihre Anfrage ohne Änderungen und führt keine Rundungen, Zeitverschiebungen oder Dateninterpolationen durch.

Um den gesamten angeforderten Bereich abzudecken, wird die Gesamtzahl der Aggregationszeiträume mit der Aufrundungsdivision berechnet:

Number of windows = ceiling(Range duration / Window size)

Jeder Bucket beginnt sequenziell am Anfang Ihres Bereichs. Wenn das Hinzufügen eines weiteren Fensters in voller Größe über die angeforderte Endzeit hinausgehen würde, wird das letzte Fenster am Ende des Zeitraums abgeschnitten.

So funktioniert die Bucket-Erstellung

Wenn Sie Rollups mit nicht teilbaren Bereichen anfordern, gelten die folgenden Regeln:

  • Die Einteilung in Buckets beginnt am Anfang des angeforderten Zeitraums (range.startTime oder range.start) und wird in Schritten entsprechend der Fenstergröße (windowSize oder windowSizeDays) fortgesetzt.
  • Der letzte chronologische Bucket wird am Ende des angeforderten Zeitraums (range.endTime oder range.end) begrenzt. Er umfasst also einen kürzeren Zeitraum als die angeforderte Fenstergröße.
  • Die zurückgegebenen RollupDataPoint- oder DailyRollupDataPoint-Objekte geben explizit eigene Start- und Endzeitstempel an, mit denen Sie die tatsächliche Dauer des gekürzten Bucket prüfen können.
  • Da die API zusammengefasste Daten in umgekehrter chronologischer Reihenfolge (neueste zuerst) zurückgibt, wird der letzte chronologische Bucket (der abgeschnittene) als erstes Element (index 0) in der zurückgegebenen Liste angezeigt.

Szenario: 12-Minuten-Bereich mit einem 5-Minuten-Fenster

Angenommen, ein Client fordert einen Rollup für einen Zeitraum von 12 Minuten mit einem windowSize von 5 Minuten an:

  • range.startTime: 10:00:00
  • range.endTime: 10:12:00 (Gesamtdauer: 12 Minuten)
  • windowSize: 5 minutes

Da 12 Minuten kein Vielfaches von 5 Minuten ist (12 = 5 * 2 + 2), akzeptiert die API die Anfrage und berechnet die Anzahl der Zeitfenster als ceiling(12 / 5) = 3.

Daraus ergeben sich die folgenden drei chronologischen Gruppen:

  1. Bucket 1:[10:00:00, 10:05:00) – Dauer: 5 Minuten (vollständiges Fenster)
  2. Bucket 2:[10:05:00, 10:10:00) – Dauer: 5 Minuten (gesamtes Fenster)
  3. Bucket 3 (abgekürzt): [10:10:00, 10:12:00) – Dauer: 2 Minuten (abgekürzt bei range.endTime)

Auswirkungen auf aggregierte Werte

Da das letzte Fenster eine kürzere Dauer hat, sind additive Messwerte (z. B. die Summe oder Anzahl der Schritte) im gekürzten Bucket allein aufgrund des kürzeren Zeitraums niedriger.

Wenn ein Nutzer während dieser gesamten 12 Minuten mit einer gleichmäßigen Geschwindigkeit von 100 Schritten pro Minute geht:

  • Bucket 1 (10:00–10:05): 500 Schritte (5 Minuten × 100 Schritte/Minute)
  • Bucket 2 (10:05–10:10): 500 Schritte (5 Minuten × 100 Schritte/Minute)
  • Bucket 3 (10:10–10:12): 200 Schritte (2 Minuten × 100 Schritte/Minute)

Beispiel für eine API-Antwort mit Sortierung

Da die API Ergebnisse in umgekehrter chronologischer Reihenfolge zurückgibt, wird der gekürzte Bucket als erstes Element in der zurückgegebenen Liste angezeigt:

{
  "rollupDataPoints": [
    {
      "startTime": "2026-08-20T10:10:00Z",
      "endTime": "2026-08-20T10:12:00Z",
      "steps": {
        "countSum": "200"
      }
    },
    {
      "startTime": "2026-08-20T10:05:00Z",
      "endTime": "2026-08-20T10:10:00Z",
      "steps": {
        "countSum": "500"
      }
    },
    {
      "startTime": "2026-08-20T10:00:00Z",
      "endTime": "2026-08-20T10:05:00Z",
      "steps": {
        "countSum": "500"
      }
    }
  ]
}

Größe des Rollup-Fensters und zugrunde liegende Speicherauflösung

Der rollUp-Endpunkt akzeptiert zwar jeden windowSize von mindestens 1 Sekunde, aber für verschiedene Datentypen werden Messungen mit unterschiedlichen Samplingraten oder Intervalllängen im zugrunde liegenden Speicher aufgezeichnet und beibehalten. Messwerte für körperliche Aktivität, die von Wearables erfasst werden, z. B. steps, distance, active-minutes und active-energy-burned, werden in der Regel in 1-Minuten-Intervallen (60s) aufgezeichnet.

Beim Aggregieren von Intervalldatentypen platziert der rollUp-Endpunkt jeden aufgezeichneten Datenpunkt in den Bucket, der die startTime des Datenpunkts enthält. Die API unterteilt, interpoliert oder verteilt keine Intervall-Daten auf Unterintervall-Buckets.

Wenn Sie einen windowSize angeben, der kleiner als das zugrunde liegende Datenspeicherintervall ist (z. B. wenn Sie ein 10-Sekunden-Fenster für steps anfordern, das in 1-Minuten-Intervallen gespeichert wird):

  1. Der erste Unter-Bucket, der dem startTime des Intervalls entspricht (z. B. 10:00:00 bis 10:00:10), erhält die gesamte kumulierte Anzahl der Minute (z. B. alle 100 Schritte, die in dieser Minute aufgezeichnet wurden).
  2. Die verbleibenden Unter-Buckets innerhalb derselben Minute (10:00:10 bis 10:00:20, 10:00:20 bis 10:00:30 usw.) erhalten keine Datenpunkte, da in diesen Zeiträumen kein Intervall beginnt.

Das führt zu „spitzenartigen“ Daten, bei denen der Wert des gesamten Intervalls im ersten Unterfenster konzentriert ist.

Damit Sie gleichmäßig verteilte und aussagekräftige Aggregate erhalten, legen Sie windowSize immer auf eine Dauer fest, die der zugrunde liegenden Speicherauflösung des Zieldatentyps entspricht oder größer ist (z. B. 60s oder größer für steps). Die Speicherauflösung und das empfohlene Mindestzeitfenster für die Zusammenfassung für jeden Datentyp finden Sie in der Referenz zu Google Health API-Datentypen.

Gesundheitsdaten eines Nutzers aktualisieren

Verwenden Sie den patch-Endpunkt, um die Gesundheitsdaten eines Nutzers zu aktualisieren.

Mit dem Endpunkt patch wird ein vorhandener Datensatz anhand des in der Anfrage-URL angegebenen Bezeichners aktualisiert. Geben Sie die Kennung eines zuvor eingefügten Datenpunkts an. Die API überschreibt den vorhandenen Datensatz.

Die Intervall-Zeitstempel (startTime und endTime) eines Datenpunkts können auch vom Inhaber des Datensatzes aktualisiert oder von Upstream-Plattformen wie Health Connect übernommen werden. Weitere Informationen zur Unveränderlichkeit von Zeitstempeln finden Sie im Leitfaden zur Datenverwaltung. Ein Beispiel für das Aktualisieren von Intervall-Zeitstempeln finden Sie unter Intervall-Zeitstempel für vorhandene Daten aktualisieren.

Wann sollte der Datenpunkt-Identifier verwendet werden?

Die Datenpunkt-ID ist in den folgenden Szenarien unerlässlich:

  • Gezielte Aktualisierungen:Wenn Sie eine bestimmte Messung aktualisieren möchten, geben Sie die zugehörige Kennung in der patch-Anfrage an.
  • Löschungen:Wenn Sie die Kennung beibehalten, kann Ihre Anwendung den Datensatz später über den batchDelete-Endpunkt löschen.

Hier ist ein Beispiel dafür, wie ein Nutzer seinen Körperfettwert auf einer Waage namens „HumanScale“ des Unternehmens „Scales R Us“ aktualisiert. Der neue Körperfettwert des Nutzers beträgt am 10.03.2026 20 %:

Anfrage

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

Antwort

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

Zeitstempel für vorhandene Daten aktualisieren

Wenn Sie die startTime oder endTime eines vorhandenen Intervall-Datenpunkts aktualisieren möchten, senden Sie eine PATCH-Anfrage an den Ressourcen-URI des Datenpunkts. Nur der ursprüngliche Ersteller oder Inhaber eines Datensatzes kann seine Felder ändern. Anwendungen können keine Datenpunkte bearbeiten, die sie nicht selbst erstellt haben.

Hintergrundinformationen zur Unveränderlichkeit von Zeitstempeln, Upstream-Updates von Health Connect und Auswirkungen des Caching finden Sie im Leitfaden zur Datenverwaltung.

Im folgenden Beispiel wird gezeigt, wie eine Inhaber-App die Zeitstempel für Intervalle eines vorhandenen Trinkprotokolls über den patch-Endpunkt aktualisiert:

Anfrage

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

Antwort

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

Lebensmittel eintragen

Wenn Sie ein Lebensmittel protokollieren möchten, senden Sie eine POST-Anfrage an den Endpunkt nutrition-log dataPoints. Der Anfragetext enthält ein DataPoint-Objekt mit einem nutritionLog-Objekt. Weitere Informationen findest du im Ernährungsleitfaden.

Beispiel:

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

Antwort

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

Gesundheitsdaten von Nutzern löschen

Verwende die Methode batchDelete, um ein Array mit Fitbit App-Daten eines Nutzers zu löschen.

Hier ist ein Beispiel, in dem ein Nutzer zuvor seinen Körperfettanteil auf einer Waage aufgezeichnet hat, die Aufzeichnung aber löschen möchte. user-id und data-point-id aus der ursprünglichen Einfügeaktion verwenden:

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Antwort

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

Geräteinformationen finden

Mit dem list-Endpunkt können Sie die Liste der Geräte abrufen, die mit dem Konto eines Nutzers gekoppelt sind. Dazu gehören die Modellinformationen des Geräts (deviceVersion) und der Zeitpunkt der letzten Synchronisierung mit der Google Health App (lastSyncTime).

Die Listenkonfiguration und die Synchronisierungsinformationen sind nützlich, um Synchronisierungsprobleme zu beheben oder Verlaufsdaten seit der letzten Synchronisierungszeit abzurufen.

Beispiel:

Anfrage

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

Verlaufsdaten abfragen

Einer der Hauptvorteile der Google Health API ist die Möglichkeit, die Leistung eines Nutzers zu verfolgen und seine Vitalparameter über einen längeren Zeitraum zu überwachen. Sie können die Daten eines Nutzers abfragen, die bis zum Zeitpunkt der Aufzeichnung zurückreichen. Die API unterliegt keinen Einschränkungen hinsichtlich der Menge an Verlaufsdaten, die Ihre Anwendung nutzen kann.

Für das Abfragen von Verlaufsdaten gelten jedoch weiterhin die standardmäßigen Ratenbeschränkungen. Um die Systemstabilität zu gewährleisten und übermäßige Nutzlasten zu vermeiden, verwendet die Google Health API die automatische Paginierung mit endpunktspezifischen Seitengrößen. Beachten Sie die folgenden Grenzen und Verhaltensweisen:

  • Automatische Paginierung:Wenn Sie einen langen Zeitraum abfragen, gibt die API nur die erste Seite der Ergebnisse bis zur Obergrenze für die Seitengröße für diesen Endpunkt zurück, zusammen mit einem nextPageToken. Sie müssen nextPageToken verwenden, um nachfolgende Seiten anzufordern.
  • Variable Seitengrößen:Die Obergrenzen hängen vom Endpunkt und Datentyp ab. Für die meisten Datentypen ist die Seitengröße auf maximal 10.000 begrenzt. Bei bestimmten Datentypen wie exercise und sleep ist die Standard- und maximale Seitengröße jedoch auf 25 begrenzt. Wenn ein Client beispielsweise alle Schlafdaten der letzten zehn Jahre anfordert, gibt die API auf der ersten Seite trotzdem nur 25 Schlafsitzungen zurück.
  • Einschränkungen für den Rollup-Zeitraum:Für Endpunkte für das Zusammenfassen und Aggregieren von Daten (z. B. rollUp und dailyRollUp) sind Abfragezeiträume je nach Datentyp eingeschränkt:
    • Ein maximaler Zeitraum von 14 Tagen für calories-in-heart-rate-zone, heart-rate, active-minutes und total-calories.
    • Für alle anderen Rollup-Datentypen gilt ein maximaler Zeitraum von 90 Tagen.

Je nach Menge der Verlaufsdaten, die Ihre Anwendung benötigt, müssen Sie die Seiten sequenziell durchlaufen, um das gesamte Dataset abzurufen. Berücksichtigen Sie dies beim Entwerfen des Datensynchronisierungsprozesses Ihrer Anwendung.

Damit Sie optimale Leistung erzielen und API-Fehler vermeiden, sollten Sie beim Abfragen von Verlaufsdaten die folgenden Richtlinien beachten:

Phasensynchronisierung von Daten (aktive und selten genutzte Daten)

  • Erster „Hot“-Ladevorgang:Während der primären Ladesequenz werden nur die Daten der letzten 7–14 Tage abgerufen und gerendert. So sehen Nutzer Daten sofort, ohne auf zeitaufwendige Abfragen warten zu müssen.
  • Kalter Hintergrund-Load:Delegieren Sie das Abrufen älterer Verlaufsdaten an eine asynchrone Warteschlange mit niedrigerer Priorität oder einen Hintergrundprozess, nachdem die primäre Benutzeroberfläche gerendert wurde.

Abfrage-Chunking für die Aggregation

  • Da für Rollup- und tägliche Rollup-Endpunkte ein maximaler Zeitraum gilt (14 oder 90 Tage, je nach Datentyp), müssen Sie umfangreiche historische Aggregationsabfragen in kleinere, sequenzielle Intervalle innerhalb dieser Grenzwerte aufteilen.
  • Führen Sie diese untergeordneten Anfragen in Batches oder sequenziell aus, um die Parallelitätslimits einzuhalten und stetige Fortschrittsanzeigen in der Benutzeroberfläche zu ermöglichen.

Vorab aggregierte Roll-ups nutzen

Stellen Sie Übersichts-Dashboards und Trenddiagramme so um, dass sie vorab aggregierte Zusammenfassungsendpunkte wie DailyRollUpDataPoints verwenden. Dadurch wird der Rechenaufwand im Backend und die Netzwerkübertragungszeit zum Client drastisch reduziert.

Robuste Fehlerbehandlung (intelligente Wiederholungsversuche)

  • Implementieren Sie eine strikte Verarbeitung des exponentiellen Backoffs, wenn Ratenbeschränkungen (429 Too Many Requests) und Server-Gateway-Timeouts (504 Gateway Timeout) auftreten. Wiederholen Sie große, fehlgeschlagene Nutzlasten niemals sofort. Sofortige Wiederholungsversuche führen zu einer Überlastung des Backends und zu einer Verschlechterung des Systems.