Endpoints

Esta página oferece 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 delas.

Convenções da API REST

A API Google Health segue os padrões das Propostas de melhoria da API do Google (AIP), especificamente AIP-127 (transcodificação HTTP e gRPC) e 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 é feito principalmente para solicitações GET (buscar um recurso) ou LIST (filtragem/paginação), mas também é usado para operações DELETE.

  • Posicionamento: anexado ao URL após um ?.
  • Sintaxe: pares de chave-valor separados por &.
  • Mapeamento: cada campo na mensagem de solicitação que não faz parte do modelo de caminho do URL é mapeado para um parâmetro de consulta.
  • Melhor para: tipos simples (strings, números inteiros, enums) e campos repetidos.

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 muito grandes 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.
  • Melhor para: objetos complexos, mensagens aninhadas e dados sensíveis.

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 mudar.

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

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

Principais diferenças em resumo

Recurso Parâmetros de consulta Corpo da solicitação
Orientação da AIP Usado para operações de pesquisa, filtragem e leitura. Usado para operações de gravação.
Visibilidade Visível no histórico do navegador e nos registros do servidor. Oculto do URL.
Complexidade Limitado a estruturas simples ou repetidas. Oferece suporte a objetos JSON aninhados.
Codificação Precisa ser codificado por URL (por exemplo, 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 oferece suporte ao padrão ISO-8601 para valores de data com as seguintes condições:

  • Um ano de 4 dígitos YYYY
  • Valores de ano no intervalo de 0000 a 9999
  • Nenhuma aplicação de restrições de data de início implícitas 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

Esta seção fornece um índice de tarefas comuns da API Google Health e exemplos de cada uma delas.

Receber o ID de usuário do Fitbit ou do Google

Depois que um usuário dá consentimento pelo Google OAuth 2.0, a resposta do token não contém o ID de usuário do Fitbit ou do Google. Para receber o ID de usuário, chame o getIdentity endpoint. getIdentity retorna o ID de usuário legado do Fitbit e o ID de usuário do Google.

Recomendamos que, assim que um novo usuário der consentimento pelo OAuth, você chame o endpoint getIdentity e armazene os dois IDs de usuário. Isso oferece compatibilidade com versões anteriores e futuras na sua integração.

Exemplo:

Solicitação

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

Resposta

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

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

Use o list endpoint para um tipo de dados específico para receber dados detalhados ou intradiários coletados ao longo do dia em intervalos compatíveis para 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"
}

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 de 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/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": ""
}

Filtrar dados por fontes de dados, como wearables

Use o reconcile endpoint para receber dados por uma "família de fontes de dados" em um stream reconciliado.

Confira um exemplo de filtragem apenas do sono registrado pelo rastreador para o dia após 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": ""
}

Agregar pontos de dados em um período

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

Ao chamar o endpoint rollUp, forneça o corpo da solicitação que representa o período necessário no horário civil do usuário. Exemplo:

Solicitação

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

Resposta

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

Agregar dados em um ou vários dias

O dailyRollUp endpoint precisa ser usado quando você quiser agregar dados em um ou vários dias, conhecido como windowSize. Forneça o intervalo de tempo civil fechado-aberto para o intervalo necessário no corpo da solicitação. Dependendo do tipo de dados, você vai receber a soma ou a média do intervalo.

Exemplo:

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

Resposta

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

Inserir ou atualizar os dados de saúde de um usuário

Use o patch endpoint para inserir ou atualizar os dados do app Fitbit de um usuário.

Confira um exemplo em que um usuário registrou a 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-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
  }
}

Resposta

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

Excluir dados de saúde do usuário

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

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

Resposta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}
Anterior
Bibliotecas de clientes
Avançar
Links universais e de apps