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 (HTTP and gRPC Transcoding) e AIP-131 fino a AIP-135 (Standard Methods). 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/impaginazione), ma viene utilizzato anche per le operazioni DELETE.

  • Posizionamento: aggiunto all'URL dopo un ?.
  • Sintassi: coppie chiave-valore separate da &.
  • Mapping: 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, enumerazioni) 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.
  • Mapping: definito 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 a 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"
}

Principali differenze a colpo d'occhio

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:

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

Intestazioni

Per eseguire gli endpoint dell'API Google Health è necessario utilizzare le intestazioni e il 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à dell'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 dispositivi indossabili

Utilizza l'reconcile endpoint per recuperare i dati in base a una "famiglia di origini dati" in uno stream riconciliato.

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

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"
  }
}
Indietro
Librerie client
Avanti
Link universali e di app