Endpoints

Nesta página, apresentamos uma visão geral das convenções da API REST, além de um índice de tarefas comuns da API Google Health e exemplos de cada uma.

Convenções da API REST

A API Google Health segue os padrões das Propostas de melhoria da API do Google (AIP, na sigla em inglês), especificamente a AIP-127 (transcodificação HTTP e gRPC) e as AIP-131 a AIP-135 (métodos padrão). Esses padrões definem como os dados são mapeados de uma mensagem proto para uma solicitação HTTP.

Parâmetros de consulta

Os parâmetros de consulta são usados quando os dados fazem parte do URL. Isso é principalmente para solicitações GET (busca de um recurso) ou LIST (filtragem/paginação), mas também é usado para operações DELETE.

  • Posição: anexado ao URL após um ?.
  • Sintaxe: pares de chave-valor separados por &.
  • Mapeamento: todos os campos na mensagem de solicitação que não fazem parte do modelo de caminho do URL são mapeados para um parâmetro de consulta.
  • Ideal para: tipos simples (strings, ints, enums) e campos repetidos.

Para uma lista detalhada de formatos de filtro, referências de campo, regras de validação e exemplos, consulte o guia de dados de filtro.

Exemplo de sintaxe:

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 da solicitação

O corpo da solicitação é usado quando os dados modificam o estado de um recurso ou são grandes demais para um URL. O corpo geralmente é uma representação JSON do próprio recurso. Normalmente usado para operações POST, PATCH e PUT.

  • Posicionamento: dentro do payload HTTP (não visível no URL).
  • Sintaxe: formatado como um objeto JSON.
  • Mapeamento: definido na anotação google.api.http.
    • body: "*" significa que a mensagem inteira é o corpo.
    • body: "resource_name" significa que apenas um campo específico no proto é o corpo.
  • Ideal para: objetos complexos, mensagens aninhadas e dados sensíveis.

Para diretrizes detalhadas sobre tamanhos de janelas de rollup, regras de agrupamento e exemplos de agregação, consulte o guia de dados agregados.

Exemplo de sintaxe:

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

O caso híbrido

Em um método Update compatível com AIP-134 ou uma operação PATCH, ambos são usados. O URL contém o nome do recurso, o corpo contém os dados atualizados do recurso e um parâmetro de consulta (geralmente update_mask) especifica quais campos serão alterados.

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

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

Resumo das principais diferenças

Recurso Parâmetros de consulta Corpo da solicitação
Orientações do AIP Usado para operações de pesquisa, filtragem e leitura. Usado para operações de gravação.
Visibilidade Visíveis no histórico de navegação e nos registros do servidor. Oculto do URL.
Complexidade Limitado a estruturas simples ou repetidas. Oferece suporte a objetos JSON profundamente aninhados.
Codificação Precisa ser codificado em URL (por exemplo, os espaços se tornam %20). Codificação JSON padrão.

Datas

Todas as datas na API Google Health são exibidas no formato YYYY-MM-DD. A API Nutrition é compatível com o padrão ISO-8601 para valores de data com as seguintes condições:

  • Um ano com 4 dígitos YYYY
  • Valores de ano no intervalo de 0000 a 9999
  • Nenhuma restrição de data de início implícita pelo padrão ISO-8601 ou outra época

Cabeçalhos

A execução dos endpoints da API Google Health exige o uso dos cabeçalhos e do token de acesso adequados. O cabeçalho a seguir é recomendado para solicitações GET e POST:

Authorization: Bearer access-token
Accept: application/json

Índice de tarefas da API

Nesta seção, apresentamos um índice de tarefas comuns da API Google Health e exemplos de cada uma.

Encontrar o ID do usuário do Fitbit ou do Google

Depois que um usuário dá o consentimento do usuário pelo OAuth 2.0 do Google, a resposta do token não contém o ID do usuário do Fitbit ou do Google. Chame o endpoint getIdentity imediatamente depois de trocar o código de autorização para recuperar legacyUserId e healthUserId e verifique se a Conta do Google do usuário está vinculada ao Google Health. Se a conta ainda não estiver vinculada, getIdentity vai retornar 400 Bad Request com o motivo ACCOUNT_NOT_LINKED (consulte Processar Contas do Google não vinculadas).

Exemplo:

Solicitação

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

Resposta (200 OK)

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

Resposta (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"
        }
      }
    ]
  }
}

Receber dados intradiários ou detalhados coletados ao longo de um dia

Use o endpoint list para um tipo de dados específico para receber dados intradia ou detalhados coletados ao longo do dia em intervalos compatíveis com esse tipo de dados.

Exemplo:

Solicitação

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

Resposta

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

Ter uma visualização reconciliada dos dados de intervalo

Para recuperar dados de intervalo sem registros sobrepostos ou conflitos multidispositivo, chame o endpoint reconcile. O endpoint de reconciliação elimina automaticamente a duplicação de intervalos sobrepostos em lotes de sincronização e vários dispositivos de gravação, retornando um fluxo contínuo e autoritativo adequado para renderizar linhas do tempo de atividades e calcular durações.

Para entender por que os dispositivos conectados produzem intervalos sobrepostos e uma comparação operacional entre list e reconcile, consulte o Guia de gerenciamento de dados.

O exemplo a seguir compara a resposta de list (que retorna os dois registros sobrepostos) com reconcile (que resolve o conflito retornando o registro oficial) para um usuário com duas sessões de exercício sobrepostas:

Lista bruta

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

Reconciliado

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

A reconciliação resolve sessões conflitantes eliminando a duplicação e selecionando o registro oficial, em vez de sintetizar uma união de tempo artificial (como 11:00:00Z a 11:50:00Z). A resposta reconciliada retorna o ponto de dados vencedor (7797422996486764704) com o intervalo registrado original (11:20:00Z a 11:50:00Z), preservando a integridade da telemetria e das métricas medidas da sessão.

Filtrar dados

Para recuperar subconjuntos específicos de registros de pontos de dados que correspondem a critérios como intervalo de tempo, data ou horário de observação, use o endpoint list ou reconcile com um parâmetro filter.

Para diretrizes detalhadas, regras de formatação, erros de validação e exemplos de consulta, consulte o guia de filtragem de dados.

Filtrar por família de fontes de dados

Para isolar ou agregar dados de tipos específicos de fontes (por exemplo, dispositivos wearable físicos em comparação com entradas manuais), use o parâmetro dataSourceFamily.

Para diretrizes detalhadas, famílias compatíveis e exemplos de solicitação e resposta para reconcile, rollUp e dailyRollUp, consulte Filtrar por família de fonte de dados no guia "Filtrar dados".

Filtrar dados por um horário de início civil do intervalo

Use o endpoint list com um parâmetro filter para filtrar dados por horário civil ou um intervalo.

Exemplo:

Solicitação

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

Resposta

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

Filtrar dados por um horário físico de observação de amostra

Use o endpoint list com um parâmetro filter para filtrar dados por horário físico de observação da amostra.

Exemplo:

Solicitação

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

Resposta

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

Filtrar e agregar por família de fonte de dados

Uma família de fontes de dados é um agrupamento lógico de fontes de dados, como smartwatches, apps para dispositivos móveis ou entradas manuais. Ele permite isolar ou agregar dados de tipos específicos de fontes (por exemplo, dispositivos wearable físicos em comparação com entradas manuais).

Os endpoints reconcile, rollUp e dailyRollUp são compatíveis com o parâmetro dataSourceFamily. O mecanismo de transmissão depende do endpoint:

Endpoint (método HTTP) Mecanismo
reconcile (GET) Transmita dataSourceFamily como um parâmetro de consulta de URL.
rollUp (POST) Transmita dataSourceFamily como um campo no corpo da solicitação JSON.
dailyRollUp (POST) Transmita dataSourceFamily como um campo no corpo da solicitação JSON.

Famílias de fontes de dados compatíveis

A tabela a seguir descreve os valores de dataSourceFamily compatíveis:

Opção Descrição
users/me/dataSourceFamilies/all-sources Valor padrão. Retorna pontos de dados reconciliados em todas as fontes de dados próprias e de terceiros registradas. Os dados de apps de terceiros serão retornados com essa opção (por exemplo, passos do smartwatch + passos do app de terceiros + passos do smartphone + passos manuais).
users/me/dataSourceFamilies/google-wearables Inclui dados registrados por dispositivos de monitoramento do Google e da Fitbit (como trackers Fitbit e o Pixel Watch). Exclui dados registrados manualmente e dados estimados pelo smartphone. Use essa opção quando sua integração exigir telemetria de sensor bruta registrada diretamente pelo hardware do wearable.
users/me/dataSourceFamilies/google-sources Inclui fontes próprias do Google e do Fitbit. Isso inclui registros de dispositivos de monitoramento físico, dados da Conexão Saúde e todas as entradas manuais registradas por apps próprios (como o app Fitbit ou o Google Fit).

Para receber um fluxo de dados reconciliado de uma família de fontes de dados específica, chame o endpoint reconcile com o parâmetro de consulta dataSourceFamily.

Por exemplo, a solicitação GET a seguir busca o sono registrado pelo rastreador no dia seguinte a 03/03/2026:

Solicitação

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

Resposta

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

Para agregar pontos de dados em um tamanho de janela específico restrito a uma família de fontes de dados específica, chame o endpoint rollUp e transmita o campo dataSourceFamily no corpo da solicitação JSON.

A solicitação POST a seguir consulta as contagens de passos de caminhada intradiárias em intervalos de hora em hora (3600s), agregadas exclusivamente de dispositivos wearable:

Solicitação

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

Resposta

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

Para agregar pontos de dados diários de uma família de fontes específica, chame o endpoint dailyRollUp e transmita o campo dataSourceFamily no corpo da solicitação.

Por exemplo, a solicitação a seguir calcula os resumos diários dos passos do usuário, incluindo todas as fontes próprias do Google e do Fitbit (dispositivos wearable + entradas manuais):

Solicitação

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

Resposta

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

Agregue pontos de dados em um período

Use o endpoint rollUp para retornar o conjunto de pontos de dados com base em uma janela em segundos (windowSize), em um intervalo de datetime no horário físico do usuário (em UTC).

Ao chamar o endpoint rollUp, forneça o corpo da solicitação que representa o horário de fechamento e abertura necessário range e windowSize (pelo menos "1s"). Para diretrizes detalhadas sobre os requisitos de windowSize, alinhamento da resolução de armazenamento, regras de agrupamento e exemplos de solicitação e resposta, consulte Agregação em intervalos de tempo físico no guia de dados agregados.

Agregue dados de um ou vários dias.

Use o endpoint dailyRollUp para agregar dados de um único dia ou de vários dias (windowSizeDays). Forneça o horário civil fechado-aberto range para o intervalo necessário no corpo da solicitação. Dependendo do tipo de dados, o endpoint retorna a soma ou a média de cada janela.

Para detalhes sobre o comportamento de agregação diária, o processamento de horário civil, os limites de intervalo por solicitação e exemplos de solicitação e resposta, consulte Agregação em dias corridos no guia de dados agregados.

Atualizar os dados de saúde de um usuário

Use o endpoint patch para atualizar os dados de saúde de um usuário.

O endpoint patch atualiza um registro com base no identificador especificado no URL da solicitação. Informe o identificador de um ponto de dados inserido anteriormente. A API substitui o registro atual.

Os carimbos de data/hora de intervalo de um ponto de dados (startTime e endTime) também podem ser atualizados pelo proprietário do registro ou propagados de plataformas upstream, como o Conexão Saúde. Para detalhes sobre a mutabilidade do carimbo de data/hora, consulte o guia de gerenciamento de dados. Para ver um exemplo de atualização de carimbos de data/hora de intervalo, consulte Atualizar carimbos de data/hora de intervalo para dados atuais.

Quando usar o identificador de ponto de dados

O identificador do ponto de dados é essencial nos seguintes cenários:

  • Atualizações segmentadas: para atualizar uma medição específica, forneça o identificador dela na solicitação patch.
  • Exclusões: ao reter o identificador, o aplicativo pode excluir o registro mais tarde usando o endpoint batchDelete.

Veja um exemplo em que um usuário atualiza a leitura de gordura corporal em uma balança chamada "HumanScale" da empresa "Scales R Us". A nova leitura de gordura corporal do usuário é de 20% para a data de 10/03/2026:

Solicitação

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

Resposta

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

Atualizar carimbos de data/hora de intervalo para dados atuais

Para atualizar os carimbos de data/hora do intervalo (startTime e endTime em payloads JSON REST ou start_time e end_time em gRPC) de um ponto de dados, envie uma solicitação PATCH para o URI do recurso do ponto de dados. Somente o criador ou proprietário original de um registro pode modificar os campos dele. Os aplicativos não podem editar pontos de dados que não criaram.

Para saber mais sobre a mutabilidade do carimbo de data/hora, as atualizações upstream da Conexão Saúde e as implicações do armazenamento em cache, consulte o guia de gerenciamento de dados.

O exemplo a seguir demonstra um aplicativo proprietário atualizando os carimbos de data/hora de intervalo de um registro de hidratação usando o endpoint patch:

Solicitação

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

Resposta

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

Registrar um alimento

Para registrar um alimento, envie uma solicitação POST para o endpoint nutrition-log dataPoints. O corpo da solicitação contém um DataPoint com um objeto nutritionLog. Para mais informações, consulte o guia de nutrição.

Exemplo:

Solicitação

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

Resposta

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

Excluir dados de saúde do usuário

Use o método batchDelete para excluir uma matriz de dados do app Fitbit de um usuário.

Veja um exemplo em que um usuário registrou a gordura corporal em uma balança, mas quer excluir o registro. Usando o user-id e o data-point-id da ação de inserção original:

Solicitação

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

Resposta

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

Encontrar informações do dispositivo

Use o endpoint list para recuperar a lista de dispositivos pareados com a conta de um usuário. Isso inclui as informações do modelo do dispositivo (deviceVersion) e a última vez que ele foi sincronizado com o app Google Health para dispositivos móveis (lastSyncTime).

As informações de configuração e sincronização da lista são úteis para resolver problemas de sincronização ou buscar dados históricos desde a última sincronização.

Exemplo:

Solicitação

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

Resposta

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

Consultar dados históricos

Um dos principais benefícios da API Google Health é a capacidade de acompanhar o desempenho de um usuário e monitorar os sinais vitais de saúde dele por longos períodos. É possível consultar os dados de um usuário desde o início do registro. A API não impõe limitações ou restrições à quantidade de dados históricos que o aplicativo pode consumir.

No entanto, a consulta de dados históricos ainda é regida por limites de taxa padrão. Para gerenciar a estabilidade do sistema e evitar payloads excessivos, a API Google Health usa paginação automática com tamanhos de página específicos do endpoint. Observe os seguintes limites e comportamentos:

  • Paginação automática: se você consultar um longo período de dados, a API vai retornar apenas a primeira página de resultados até o limite de tamanho da página para esse endpoint, além de um nextPageToken. Use o nextPageToken para solicitar as páginas seguintes.
  • Tamanhos de página variáveis: os limites de limitação dependem do endpoint e do tipo de dados. Para a maioria dos tipos de dados, o tamanho das páginas é limitado a no máximo 10.000. No entanto, para determinados tipos de dados, como exercise e sleep, o tamanho padrão e máximo da página é limitado a 25. Por exemplo, se um cliente solicitar todos os dados de sono dos últimos 10 anos, a API ainda vai retornar apenas 25 sessões de sono na primeira página.
  • Restrições de período de rollup: para endpoints de rollup e agregação de dados (como rollUp e dailyRollUp), os períodos de consulta são restritos com base no tipo de dados:
    • Um período máximo de 14 dias para calories-in-heart-rate-zone, heart-rate, active-minutes e total-calories.
    • Um período máximo de 90 dias para todos os outros tipos de dados de visualização completa.

Dependendo do volume de dados históricos que seu aplicativo precisa, a recuperação de todo o conjunto de dados exigirá a paginação sequencial das páginas. Lembre-se disso ao projetar o processo de sincronização de dados do aplicativo.

Para garantir o desempenho ideal e evitar erros de API, siga estas diretrizes ao consultar dados históricos:

Sincronização de dados em fases (carga quente x carregamento a frio)

  • Carregamento "quente" inicial: busque e renderize apenas os dados mais recentes de 7 a 14 dias durante a sequência de carregamento principal. Isso garante que os usuários vejam os dados imediatamente, sem esperar por consultas de longa duração.
  • Carregamento "frio" em segundo plano: delegue a recuperação de dados históricos mais antigos a uma fila assíncrona de menor prioridade ou a um processo em segundo plano depois que a interface principal for renderizada.

Divisão de consultas para agregação

  • Como os endpoints de rollup e rollup diário aplicam um limite máximo de período (14 ou 90 dias, dependendo do tipo de dados), é necessário dividir as consultas de agregação histórica grandes em intervalos menores e sequenciais dentro desses limites.
  • Agrupe ou sequencie essas subconsultas com segurança para respeitar os limites de simultaneidade e manter indicadores de progresso da interface estáveis.

Aproveitar as consolidações pré-agregadas

Reestruture os painéis de visão geral e os gráficos de tendências para usar endpoints de resumo pré-agregados (como DailyRollUpDataPoints). Isso reduzirá drasticamente a sobrecarga de computação no back-end e o tempo de transferência de rede para o cliente.

Tratamento de erros resiliente (novas tentativas inteligentes)

  • Implemente um tratamento rigoroso de espera exponencial ao encontrar limites de taxa (429 Too Many Requests) e tempos limite de gateway do servidor (504 Gateway Timeout). Nunca tente reenviar payloads grandes que falharam imediatamente. As novas tentativas instantâneas multiplicam o congestionamento do back-end e agravam a degradação do sistema.
Anterior
Bibliotecas de clientes
Avançar
Filtros