Endpoint

Questa pagina fornisce una panoramica delle convenzioni dell'API REST, insieme a un indice delle attività comuni dell'API Google Health ed esempi di ciascuna.

Convenzioni dell'API REST

L'API Google Health segue gli standard delle proposte di miglioramento delle API Google (AIP), in particolare AIP-127 (transcodifica HTTP e gRPC) e AIP-131-AIP-135 (metodi standard). Questi standard definiscono la mappatura dei dati da un messaggio proto a una richiesta HTTP.

Parametri di query

I parametri di query vengono utilizzati quando i dati fanno parte dell'URL. Questo vale principalmente per le richieste GET (recupero di una risorsa) o LIST (filtraggio/paginazione), ma viene utilizzato anche per le operazioni DELETE.

  • Posizionamento: aggiunto all'URL dopo un ?.
  • Sintassi: coppie chiave-valore separate da &.
  • Mappatura: ogni campo nel messaggio di richiesta che non fa parte del modello del percorso URL viene mappato a un parametro di query.
  • Ideale per: tipi semplici (stringhe, numeri interi, enum) e campi ripetuti.

Esempio di sintassi:

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"

Corpo della richiesta

Il corpo della richiesta viene utilizzato quando i dati modificano lo stato di una risorsa o sono troppo grandi per un URL. Il corpo è in genere una rappresentazione JSON della risorsa stessa. In genere viene utilizzato per le operazioni POST, PATCH e PUT.

  • Posizionamento: all'interno del payload HTTP (non visibile nell'URL).
  • Sintassi: formattato come oggetto JSON.
  • Mappatura: definita nell'annotazione google.api.http.
    • body: "*" significa che l'intero messaggio è il corpo.
    • body: "resource_name" significa che solo un campo specifico nel proto è il corpo.
  • Ideale per: oggetti complessi, messaggi nidificati e dati sensibili.

Esempio di sintassi:

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"
}

Il caso ibrido

In un metodo Update conforme ad AIP-134 o in un'operazione PATCH, vengono utilizzati entrambi. L'URL contiene il nome della risorsa, il corpo contiene i dati della risorsa aggiornati e un parametro di query (in genere update_mask) specifica i campi da modificare.

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

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

Sintesi delle differenze principali

Funzionalità Parametri di query Corpo della richiesta
Indicazioni AIP Utilizzato per la ricerca, il filtraggio e le operazioni di lettura. Utilizzato per le operazioni di scrittura.
Visibilità Visibile nella cronologia del browser e nei log del server. Nascosto dall'URL.
Complessità Limitato a strutture piatte o ripetute. Supporta oggetti JSON nidificati in profondità.
Codifica Deve essere codificato nell'URL (ad esempio, gli spazi diventano %20). Codifica JSON standard.

Date

Tutte le date nell'API Google Health vengono visualizzate nel formato YYYY-MM-DD. L'API Nutrition supporta lo standard ISO-8601 per i valori di data con le seguenti condizioni:

  • Anno a 4 cifre YYYY
  • Valori dell'anno compresi nell'intervallo 0000-9999
  • Nessuna applicazione delle limitazioni della data di inizio implicite dallo standard ISO-8601 o da altre epoche

Intestazioni

L'esecuzione degli endpoint dell'API Google Health richiede l'utilizzo delle intestazioni e del token di accesso appropriati. L'intestazione seguente è consigliata sia per le richieste GET sia per le richieste POST:

Authorization: Bearer access-token
Accept: application/json

Indice delle attività API

Questa sezione fornisce un indice delle attività comuni dell'API Google Health ed esempi di ciascuna.

Recuperare l'ID utente Fitbit o Google

Dopo che un utente ha fornito il consenso tramite Google OAuth 2.0, la risposta del token non contiene l'ID utente Fitbit o Google. Per ottenere l'ID utente, chiama l' getIdentityendpoint. getIdentity restituisce sia l'ID utente legacy di Fitbit sia l'ID utente Google.

Ti consigliamo di chiamare l'endpoint getIdentity e di memorizzare entrambi gli ID utente non appena un nuovo utente fornisce il consenso tramite OAuth. In questo modo, la tua integrazione è compatibile con le versioni precedenti e successive.

Ad esempio:

Richiesta

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

Risposta

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

Recuperare i dati intraday o dettagliati raccolti durante la giornata

Utilizza l'list endpoint per un tipo di dati specifico per recuperare i dati intraday o dettagliati raccolti durante la giornata negli intervalli supportati per quel tipo di dati.

Ad esempio:

Richiesta

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

Risposta

{
  "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"
}

Filtrare i dati in base all'ora di inizio civile di un intervallo

Utilizza l'endpoint list con un parametro filter per filtrare i dati in base all'ora civile o a un intervallo.

Ad esempio:

Richiesta

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

Risposta

{
  "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"
}

Filtrare i dati in base all'ora fisica di osservazione di un campione

Utilizza l'endpoint list con un parametro filter per filtrare i dati in base all'ora fisica di osservazione di un campione.

Ad esempio:

Richiesta

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

Risposta

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/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": ""
}

Filtrare i dati in base alle origini dati, ad esempio i wearable

Utilizza l'reconcile endpoint per recuperare i dati per una "famiglia di origini dati" specifica. Per farlo, specifica il parametro dataSourceFamily come parametro di query.

La tabella seguente descrive le opzioni dataSourceFamily supportate:

Opzione Descrizione
users/me/dataSourceFamilies/all-sources Valore predefinito. Include i dati di tutte le origini dati disponibili.
users/me/dataSourceFamilies/google-wearables Include i dati dei dispositivi di monitoraggio Google e Fitbit (ad esempio i tracker Fitbit e Pixel Watch). Esclude i dati registrati manualmente.
users/me/dataSourceFamilies/google-sources Include i dati di Google proprietari, ad esempio i dati dei tracker e i dati registrati manualmente.

Ecco un esempio di filtro del sonno registrato dal tracker per il giorno successivo al 3 marzo 2026:

Richiesta

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

Risposta

{
  "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": ""
}

Aggregare i punti dati in un intervallo di tempo

Utilizza l'rollUp endpoint per restituire l' aggregazione dei punti dati in base a una finestra in secondi, nell'intervallo datetime in base all'ora fisica degli utenti (in UTC).

Quando chiami l'endpoint rollUp, devi fornire il corpo della richiesta che rappresenta l'intervallo di date richiesto nell'ora civile dell'utente. Ad esempio:

Richiesta

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": "30s"
}

Risposta

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

Aggregare i dati in un singolo giorno o in più giorni

L'endpoint dailyRollUp deve essere utilizzato quando vuoi aggregare i dati in un singolo giorno o in più giorni, noto come windowSize. Fornisci l'intervallo di tempo civile chiuso-aperto per l'intervallo richiesto nel corpo della richiesta. A seconda del tipo di dati, riceverai la somma o la media nell'intervallo.

Ad esempio:

Richiesta

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
}

Risposta

{
  "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"
      }
    }
  ]
}

Inserire o aggiornare i dati sulla salute di un utente

Utilizza l'patch endpoint per inserire o aggiornare i dati dell'app Fitbit di un utente.

Ecco un esempio in cui un utente ha registrato il grasso corporeo su una bilancia chiamata "HumanScale" dell'azienda "Scales R Us". La nuova lettura del grasso corporeo dell'utente è del 20% per la data del 10 marzo 2026.

Richiesta

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
content-length: 329

{
  "name": "bodyFatName",
  "dataSource": {

    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

Risposta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/2515055256096816351/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
    }
  }
}

Registrare un alimento

Per registrare un alimento, invia una richiesta POST all'endpoint dei punti dati nutrition-log. Il corpo della richiesta contiene un DataPoint con un oggetto nutritionLog. Per ulteriori informazioni, consulta la guida Nutrition.

Ad esempio:

Richiesta

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
    }
  }
}

Risposta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/2515055256096816351/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"
    }
  }
}

Eliminare i dati sulla salute dell'utente

Utilizza l'batchDelete endpoint per eliminare un array di dati dell'app Fitbit di un utente.

Ecco un esempio in cui un utente ha registrato in precedenza il grasso corporeo su una bilancia, ma vuole eliminare il record. Utilizzando il user-id e data-point-id dall'azione di inserimento originale:

Richiesta

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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Risposta

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

Trovare le informazioni sul dispositivo

Utilizza l'endpoint list per recuperare l'elenco dei dispositivi associati all'account di un utente. Sono incluse le informazioni sul modello del dispositivo (deviceVersion) e l'ultima volta che è stato sincronizzato con l'app mobile Google Health (lastSyncTime).

Le informazioni sulla configurazione dell'elenco e sulla sincronizzazione sono utili per risolvere i problemi di sincronizzazione o recuperare i dati storici dall'ultima sincronizzazione.

Ad esempio:

Richiesta

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

Risposta

{
  "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"
      ]
    }
  ]
}

Eseguire query sui dati storici

Uno dei vantaggi principali dell'API Google Health è la possibilità di monitorare il rendimento di un utente e i suoi parametri vitali per la salute per lunghi periodi di tempo. Puoi eseguire query sui dati di un utente fino a quando sono stati registrati; l'API non impone limitazioni o restrizioni sulla quantità di dati storici che la tua applicazione può utilizzare.

Tuttavia, l'esecuzione di query sui dati storici è comunque regolata dai limiti di frequenza standard standard. Per ridurre il numero di chiamate API rispetto a questi limiti, l'API Google Health supporta l'esecuzione di query sui dati in un intervallo di date. Tieni presente i seguenti limiti di paginazione e richiesta:

  • Ogni endpoint restituisce una dimensione massima della pagina di 10.000 punti dati per pagina.
  • Gli intervalli di date delle query sono limitati a un periodo compreso tra 14 e 90 giorni per richiesta.

A seconda del volume di dati storici richiesti dalla tua applicazione, il recupero dell'intero set di dati potrebbe richiedere più richieste sequenziali e richiedere più tempo. Tienilo presente quando progetti la procedura di sincronizzazione dei dati della tua applicazione.

Per garantire prestazioni ottimali ed evitare errori API, segui queste linee guida quando esegui query sui dati storici:

Sincronizzazione dei dati in fasi (caricamento hot e caricamento completo)

  • Caricamento "hot" iniziale: recupera ed esegui il rendering solo dei dati più recenti (7-14 giorni) durante la sequenza di caricamento principale. In questo modo, gli utenti vedono immediatamente i dati senza dover attendere query a lunga esecuzione.
  • Caricamento "cold" in background: delega il recupero dei dati storici meno recenti a una coda asincrona a priorità inferiore o a un processo in background dopo il rendering dell'interfaccia utente principale.

Chunking delle query in base al tempo

  • Non richiedere intervalli di più anni o più mesi in una singola chiamata API. Suddividi le query storiche di grandi dimensioni in intervalli sequenziali più piccoli (ad esempio, 1 settimana per richiesta).
  • Esegui il batch o la sequenza di queste sottoquery in modo sicuro per rispettare i limiti di concorrenza e mantenere indicatori di avanzamento dell'interfaccia utente costanti.

Sfruttare i roll-up pre-aggregati

Ristruttura le dashboard di panoramica e i grafici delle tendenze in modo da utilizzare endpoint di riepilogo pre-aggregati (ad esempio DailyRollUpDataPoints). In questo modo, si ridurrà drasticamente il sovraccarico di calcolo sul backend e il tempo di trasferimento di rete al client.

Gestione degli errori resiliente (nuovi tentativi intelligenti)

  • Implementa una gestione rigorosa del backoff esponenziale quando incontri limiti di frequenza (429 Too Many Requests) e timeout del gateway del server (504 Gateway Timeout). Non riprovare immediatamente a eseguire payload di grandi dimensioni non riusciti. I nuovi tentativi immediati moltiplicano la congestione del backend e peggiorano il sistema.
  • Se una query va ripetutamente in timeout, esegui automaticamente il fallback a una finestra temporale più piccola (ad esempio, riduci un chunk di 1 settimana a 3 giorni).