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 é principalmente para solicitações GET (busca de um recurso) ou LIST (filtragem/paginação), mas também é usado para operações DELETE.

  • Posição: anexada ao URL após um ?.
  • Sintaxe: pares de chave-valor separados por &.
  • Mapeamento: todos os campos da 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.

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 da carga útil HTTP (não visível no URL).
  • Sintaxe: formatada como um objeto JSON.
  • Mapeamento: definido na anotação google.api.http.
    • body: "*" significa que toda a mensagem é 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.

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ções sobre a 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. Aceita objetos JSON profundamente 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 mostradas 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 quatro dígitos YYYY
  • Valores de ano no intervalo de 0000 a 9999
  • Não há aplicação de restrições de data de início implícitas pelo padrão ISO-8601 ou outra época.

Cabeçalhos

Para executar os endpoints da API Google Health, é necessário usar os cabeçalhos e o 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 conseguir o ID do usuário, chame o endpoint getIdentity. getIdentity retorna o ID do usuário legado do Fitbit e o ID do 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 intradiários ou detalhados coletados ao longo de um dia

Use o endpoint list de um tipo de dados específico para receber dados intradiários ou detalhados 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 hora 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 tempo físico de observação de amostra

Use o endpoint list com um parâmetro filter para filtrar dados por tempo 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/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 dispositivos wearable

Use o endpoint reconcile para receber dados de uma "família de fontes de dados" em um fluxo conciliado.

Confira um exemplo de filtragem apenas do sono registrado pelo rastreador no dia após 2026-03-03:

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 endpoint rollUp para retornar o agregado de pontos de dados com base em uma janela em segundos, no intervalo datetime com base no tempo físico dos usuários (em UTC).

Ao chamar o endpoint rollUp, você precisa fornecer 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 único dia ou em vários dias

O endpoint dailyRollUp deve ser usado quando você quiser agregar dados em um único dia 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 endpoint patch 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". O novo percentual de gordura corporal do usuário é de 20% em 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 endpoint batchDelete para excluir uma matriz de dados do app Fitbit de um usuário.

Este é um exemplo em que um usuário registrou a gordura corporal em uma balança, mas quer excluir o registro. Usando 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