Endpunkte

Auf dieser Seite finden Sie eine Übersicht über die REST API-Konventionen sowie einen Index gängiger Google Health API-Aufgaben und Beispiele für jede Aufgabe.

REST API-Konventionen

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

Suchparameter

Suchparameter werden verwendet, wenn die Daten Teil der URL sind. Dies gilt hauptsächlich für GET-Anfragen (Abrufen einer Ressource) oder LIST-Anfragen (Filtern/Seitenumbruch), 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, Enums) und wiederkehrende Felder.

Eine detaillierte Liste der Filterformate, Feldreferenzen, Validierungsregeln und Beispiele finden Sie im Leitfaden zum Filtern von Daten.

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 normalerweise eine JSON-Darstellung der Ressource selbst. Wird normalerweise für die Vorgänge POST, PATCH und PUT verwendet.

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

Ausführliche Richtlinien zu Rollup-Fenstergrößen, Bucketing-Regeln und Aggregationsbeispielen finden Sie im Leitfaden zu aggregierten 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-konformen Update-Methode oder einem PATCH-Vorgang werden beide verwendet. Die URL enthält den Ressourcennamen, der Text die aktualisierten Ressourcendaten und ein Suchparameter (normalerweise 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 Server-Logs. Aus der URL ausgeblendet.
Komplexität Beschränkt auf flache oder wiederholte Strukturen. Unterstützt tief verschachtelte JSON-Objekte.
Encoding Muss URL-codiert sein (Leerzeichen werden z. B. 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 mit den folgenden Bedingungen:

  • Eine vierstellige Jahreszahl YYYY
  • Jahreswerte im Bereich von 0000 bis 9999
  • Keine Durchsetzung von Einschränkungen für das Startdatum, die sich aus dem ISO-8601-Standard oder einer anderen Epoche ergeben

Header

Zum Ausführen der Google Health API-Endpunkte müssen die entsprechenden Header und Zugriffstokens verwendet werden. 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 gängiger Google Health API-Aufgaben und Beispiele für jede Aufgabe.

Fitbit- oder Google-Nutzer-ID abrufen

Nachdem ein Nutzer seine Einwilligung über Google OAuth 2.0 erteilt hat, enthält die Tokenantwort nicht die Fitbit- oder Google-Nutzer-ID. Rufe den getIdentity-Endpunkt sofort nach dem Austausch des Autorisierungscodes auf, um sowohl legacyUserId als auch healthUserId abzurufen und zu prüfen, ob das Google-Konto des Nutzers mit Google Health verknüpft ist. Wenn das Konto noch nicht verknüpft ist, gibt getIdentity 400 Bad Request mit dem Grund ACCOUNT_NOT_LINKED zurück (siehe Nicht verknüpfte Google-Konten verarbeiten).

Beispiel:

Anfrage

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

Antwort (200 OK)

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

Antwort (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

Daten abrufen, die im Laufe eines Tages erhoben wurden (Intraday- oder detaillierte Daten)

Verwende den list-Endpunkt für einen bestimmten Datentyp, um Intraday- oder detaillierte Daten abzurufen, die im Laufe des Tages in unterstützten Intervallen für diesen Datentyp erhoben 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"
}

Abgeglichene Ansicht von Intervalldaten abrufen

Wenn du Intervalldaten ohne sich überschneidende Datensätze oder Konflikte für verschiedene Geräte abrufen möchtest, rufe den reconcile-Endpunkt auf. Der Abgleichsendpunkt dedupliziert automatisch überlappende Intervalle über Synchronisierungsbatches und mehrere Aufzeichnungsgeräte hinweg und gibt einen maßgeblichen, kontinuierlichen Stream zurück, der sich für das Rendern von Aktivitätszeitachsen und das Berechnen von Dauern eignet.

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

Im folgenden Beispiel wird die Antwort von list (gibt beide sich überschneidenden Datensätze zurück) mit der von reconcile (löst den Konflikt, indem der maßgebliche Datensatz zurückgegeben wird) 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"
      }
    }
  ]
}

Beim Abgleich werden widersprüchliche Sitzungen aufgelöst, indem Duplikate entfernt und der maßgebliche Datensatz ausgewählt wird, anstatt eine künstliche Zeitunion (z. B. 11:00:00Z bis 11:50:00Z) zu erstellen. Die abgeglichene Antwort gibt den ausgewählten Datenpunkt (7797422996486764704) mit dem ursprünglich aufgezeichneten Intervall (11:20:00Z bis 11:50:00Z) zurück. So bleibt die Integrität der gemessenen Telemetrie und Messwerte dieser Sitzung erhalten.

Daten filtern

Wenn Sie bestimmte Teilmengen von Datenpunktdatensätzen abrufen möchten, die Kriterien wie einem Zeitintervall, einem Datum oder einer Beobachtungszeit entsprechen, verwenden Sie den Endpunkt list oder reconcile mit einem filter-Parameter.

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

Nach Datenquellenfamilie filtern

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

Ausführliche Richtlinien, unterstützte Familien sowie Anfrage- und Antwortbeispiele für reconcile, rollUp und dailyRollUp finden Sie im Leitfaden „Daten filtern“ unter Nach Datenquellenfamilie filtern.

Daten nach einem bürgerlichen Startzeitintervall filtern

Verwenden Sie den Endpunkt list 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 Beispielbeobachtung 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 (z. B. Smartwatches, mobile Apps oder manuelle Einträge). Sie können damit Daten aus bestimmten Arten von Quellen isolieren oder aggregieren (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 selbst erhobenen Datenquellen und Drittanbieter-Datenquellen hinweg abgeglichen wurden. Bei dieser Option werden Daten aus Drittanbieter-Apps zurückgegeben (z. B. Schritte von einer Smartwatch + Schritte aus einer Drittanbieter-App + Schritte von einem Smartphone + manuell hinzugefügte Schritte).
users/me/dataSourceFamilies/google-wearables Enthält Daten, die von Google- und Fitbit-Trackern (z. B. Fitbit-Wearables und Pixel Watch) aufgezeichnet wurden. Manuell protokollierte Daten und vom Smartphone geschätzte Daten sind ausgeschlossen. Verwenden Sie diese Option, wenn Ihre Integration Rohsensortelemetrie erfordert, die direkt von Wearable-Hardware aufgezeichnet wird.
users/me/dataSourceFamilies/google-sources Enthält eigene Google- und Fitbit-Quellen. Dazu gehören Daten von physischen Trackern, Daten von Health Connect und alle manuellen Einträge, die über eigene Apps wie die Fitbit App oder Google Fit vorgenommen wurden.

Wenn Sie einen abgeglichenen Datenstream aus einer bestimmten Datenquellenfamilie abrufen möchten, rufen Sie den Endpunkt reconcile mit dem Suchparameter 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 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 Schrittzahlen für das Gehen im Tagesverlauf in stündlichen Intervallen (3600s) abgefragt, die ausschließlich von Wearables aggregiert werden:

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 Quellfamilie aggregieren möchten, rufen Sie den Endpunkt dailyRollUp auf und übergeben Sie das Feld dataSourceFamily im Anfragetext.

In der folgenden Anfrage werden beispielsweise die täglichen Rollups für die Schritte des Nutzers berechnet, einschließlich aller Google- und Fitbit-Quellen (Wearables und 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 aggregieren

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

Wenn Sie den Endpunkt rollUp aufrufen, geben Sie den Anfragetext an, der die erforderliche geschlossene/offene Zeit range und windowSize (mindestens "1s") darstellt. Detaillierte Richtlinien zu den Anforderungen für windowSize, zur Ausrichtung der Speicherauflösung, zu Bucketing-Regeln sowie Anfrage- und Antwortbeispiele finden Sie im Leitfaden zum Aggregieren von Daten unter Über physische Zeitintervalle aggregieren.

Daten für einen einzelnen Tag oder mehrere Tage aggregieren

Verwende den Endpunkt dailyRollUp, um Daten für einen oder mehrere Tage (windowSizeDays) zu aggregieren. Gib im Anfragetext die geschlossene/offene bürgerliche Zeit range für das erforderliche Intervall an. Je nach Datentyp gibt der Endpunkt entweder die Summe oder den Durchschnitt für jedes Fenster zurück.

Weitere Informationen zum Verhalten der täglichen Aggregation, zur Verarbeitung der bürgerlichen Zeit, zu den Bereichsbeschränkungen pro Anfrage sowie Beispiele für Anfragen und Antworten finden Sie im Leitfaden zu aggregierten Daten unter Über Kalendertage hinweg aggregieren.

Gesundheitsdaten eines Nutzers aktualisieren

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

Der Endpunkt patch aktualisiert einen vorhandenen Eintrag anhand der in der Anfrage-URL angegebenen Kennung. Geben Sie die Kennung eines zuvor eingefügten Datenpunkts an. Die API überschreibt den vorhandenen Eintrag.

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

Wann die Datenpunkt-ID verwendet werden sollte

Die Datenpunkt-ID ist in den folgenden Szenarien wichtig:

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

Hier ist ein Beispiel, in dem 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 Intervalle vorhandener Daten aktualisieren

Wenn Sie die Intervallzeitstempel (startTime und endTime in REST-JSON-Nutzlasten oder start_time und end_time in gRPC) eines vorhandenen 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 erstellt haben.

Hintergrundinformationen zur Veränderbarkeit von Zeitstempeln, zu Upstream-Updates von Health Connect und zu den Auswirkungen des Cachings findest du im Leitfaden zum Datenmanagement.

Im folgenden Beispiel wird gezeigt, wie eine Inhaber-App die Intervallzeitstempel eines vorhandenen Hydrationsprotokolls mit dem Endpunkt patch 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 protokollieren

Wenn du ein Lebensmittel protokollieren möchtest, sende eine POST-Anfrage an den nutrition-log-Endpunkt dataPoints. Der Anfragetext enthält ein DataPoint-Objekt mit einem nutritionLog-Objekt. Weitere Informationen findest du im Leitfaden zur Ernährung.

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 batchDelete-Methode, um ein Array von Fitbit-App-Daten eines Nutzers zu löschen.

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

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

Verwende den list-Endpunkt, um die Liste der Geräte abzurufen, 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 mobilen Google Health App (lastSyncTime).

Die Listenkonfiguration und die Synchronisierungsinformationen sind nützlich, um Synchronisierungsprobleme zu beheben oder Verlaufsdaten seit der letzten Synchronisierung 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 Vitalwerte über einen längeren Zeitraum zu überwachen. Sie können die Daten eines Nutzers so weit zurück abfragen, wie sie aufgezeichnet wurden. Die API legt keine Beschränkungen für die Menge an Verlaufsdaten fest, die Ihre Anwendung nutzen kann.

Für die Abfrage von Verlaufsdaten gelten jedoch weiterhin die standardmäßigen Ratenbegrenzungen. Um die Systemstabilität zu gewährleisten und übermäßige Nutzlasten zu vermeiden, verwendet die Google Health API eine 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 Ergebnisseite bis zur maximalen Seitengröße für diesen Endpunkt zurück, zusammen mit einem nextPageToken. Sie müssen das nextPageToken verwenden, um nachfolgende Seiten anzufordern.
  • Variable Seitengrößen: Die Obergrenzen hängen vom Endpunkt und Datentyp ab. Bei den 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 10 Jahre anfordert, gibt die API auf der ersten Seite trotzdem nur 25 Schlafeinheiten zurück.
  • Einschränkungen für den Datumsbereich bei Roll-ups: Für Endpunkte für Daten-Roll-ups und -Aggregationen (z. B. rollUp und dailyRollUp) sind die Datumsbereiche für Abfragen je nach Datentyp eingeschränkt:
    • Ein maximaler Bereich von 14 Tagen für calories-in-heart-rate-zone, heart-rate, active-minutes und total-calories.
    • Für alle anderen Datentypen in der Zusammenfassung gilt ein maximaler Zeitraum von 90 Tagen.

Je nach Umfang der Verlaufsdaten, die Ihre Anwendung benötigt, müssen Sie zum Abrufen des gesamten Datasets die Seiten nacheinander durchgehen. Berücksichtigen Sie dies beim Entwerfen des Datensynchronisierungsprozesses Ihrer Anwendung.

Beachten Sie die folgenden Richtlinien, wenn Sie Verlaufsdaten abfragen, um eine optimale Leistung zu erzielen und API-Fehler zu vermeiden:

Phasenweise Datensynchronisierung (heißes und kaltes Laden)

  • Erstes „heißes“ Laden: Während der primären Ladesequenz werden nur die Daten der letzten 7–14 Tage abgerufen und gerendert. So sehen Nutzer die Daten sofort, ohne auf langwierige Abfragen warten zu müssen.
  • „Cold“-Laden im Hintergrund: 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 große Abfragen für historische Aggregationen in kleinere, aufeinanderfolgende Intervalle innerhalb dieser Limits aufteilen.
  • Fassen Sie diese Unterabfragen sicher in Batches oder Sequenzen zusammen, um die Limits für gleichzeitige Abfragen einzuhalten und die UI-Fortschrittsanzeigen stabil zu halten.

Vorab aggregierte Roll-ups nutzen

Strukturieren Sie Übersichts-Dashboards und Trenddiagramme so um, dass sie vorab aggregierte Zusammenfassungsendpunkte (z. B. DailyRollUpDataPoints) verwenden. Dadurch werden der Rechenaufwand im Backend und die Netzwerkübertragungszeit zum Client drastisch reduziert.

Ausfallsichere Fehlerbehandlung (intelligente Wiederholungsversuche)

  • Implementieren Sie eine strikte exponentielle Backoff-Verarbeitung, wenn Ratenbegrenzungen (429 Too Many Requests) und Server-Gateway-Zeitüberschreitungen (504 Gateway Timeout) auftreten. Wiederholen Sie große, fehlgeschlagene Nutzlasten niemals sofort. Sofortige Wiederholungsversuche vervielfachen die Backend-Überlastung und verschlimmern die Systembeeinträchtigung.
Zurück
Clientbibliotheken
Weiter
Filter