Extremos

En esta página, se proporciona una descripción general de las convenciones de la API de REST, junto con un índice de las tareas comunes de la API de Google Health y ejemplos de cada una.

Convenciones de la API de REST

La API de Google Health sigue los estándares de las Propuestas de mejora de la API de Google (AIP), específicamente AIP-127 (transcodificación de HTTP y gRPC) y AIP-131 a AIP-135 (métodos estándar). Estos estándares definen cómo se asignan los datos de un mensaje proto a una solicitud HTTP.

Parámetros de consulta

Los parámetros de consulta se usan cuando los datos forman parte de la URL. Esto es principalmente para solicitudes GET (recuperar un recurso) o solicitudes LIST (filtrado o paginación), pero también se usa para operaciones DELETE.

  • Ubicación: Se agrega a la URL después de un ?.
  • Sintaxis: Pares clave-valor separados por &.
  • Asignación: Cada campo del mensaje de solicitud que no forma parte de la plantilla de ruta de URL se asigna a un parámetro de consulta.
  • Ideal para: Tipos simples (cadenas, números enteros, enumeraciones) y campos repetidos.

Ejemplo de sintaxis:

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"

Cuerpo de la solicitud

El cuerpo de la solicitud se usa cuando los datos modifican el estado de un recurso o son demasiado grandes para una URL. Por lo general, el cuerpo es una representación JSON del recurso en sí. Se usa, por lo general, para operaciones POST, PATCH y PUT.

  • Ubicación: Dentro de la carga útil de HTTP (no visible en la URL).
  • Sintaxis: Formateado como un objeto JSON.
  • Asignación: Definido en la google.api.http anotación.
    • body: "*" significa que todo el mensaje es el cuerpo.
    • body: "resource_name" significa que solo un campo específico en el proto es el cuerpo.
  • Ideal para: Objetos complejos, mensajes anidados y datos sensibles.

Ejemplo de sintaxis:

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

El caso híbrido

En un método Update compatible con AIP-134 o una operación PATCH, se usan ambos. La URL contiene el nombre del recurso, el cuerpo contiene los datos del recurso actualizados y un parámetro de consulta (por lo general, update_mask) especifica qué campos cambiar.

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

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

Resumen de las diferencias clave

Función Parámetros de búsqueda Cuerpo de la solicitud
Orientación de la AIP Se usa para buscar, filtrar y realizar operaciones de lectura. Se usa para operaciones de escritura.
Visibilidad Visible en el historial del navegador y los registros del servidor. Oculto de la URL.
Complejidad Se limita a estructuras planas o repetidas. Admite objetos JSON anidados en profundidad.
Codificación Debe estar codificado como URL (por ejemplo, los espacios se convierten en %20). Codificación JSON estándar.

Fechas

Todas las fechas de la API de Google Health se muestran en el formato YYYY-MM-DD. La API de Nutrition admite el estándar ISO-8601 para los valores de fecha con las siguientes condiciones:

  • Un año de 4 dígitos YYYY
  • Valores de año dentro del rango de 0000 a 9999
  • No se aplica ninguna restricción de fecha de inicio implícita en el estándar ISO-8601 ni en otra época.

Encabezados

Para ejecutar los extremos de la API de Google Health, debes usar los encabezados y el token de acceso adecuados. Se recomienda el siguiente encabezado para las solicitudes GET y POST:

Authorization: Bearer access-token
Accept: application/json

Índice de tareas de la API

En esta sección, se proporciona un índice de las tareas comunes de la API de Google Health y ejemplos de cada una.

Obtén el ID de usuario de Fitbit o Google

Después de que un usuario da su consentimiento a través de Google OAuth 2.0, la respuesta del token no contiene el ID de usuario de Fitbit o Google. Para obtener el ID de usuario, llama al getIdentity extremo. getIdentity muestra el ID de usuario heredado de Fitbit y el ID de usuario de Google.

Te recomendamos que, en cuanto un usuario nuevo dé su consentimiento a través de OAuth, llames al extremo getIdentity y almacenes ambos IDs de usuario. Esto proporciona compatibilidad con versiones anteriores y posteriores en tu integración.

Por ejemplo:

Solicitud

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

Respuesta

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

Obtén datos detallados o intradiarios recopilados durante un día

Usa el list extremo para un tipo de datos específico para obtener datos detallados o intradiarios recopilados durante el día en intervalos admitidos para ese tipo de datos.

Por ejemplo:

Solicitud

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

Respuesta

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

Filtra datos por una hora de inicio civil de intervalo

Usa el extremo list con un parámetro filter para filtrar datos por hora civil o un intervalo.

Por ejemplo:

Solicitud

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

Respuesta

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

Filtra datos por la hora física de observación de una muestra

Usa el extremo list con un parámetro filter para filtrar datos por la hora física de observación de una muestra.

Por ejemplo:

Solicitud

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

Respuesta

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

Filtra datos por fuentes de datos, como wearables

Usa el reconcile extremo para obtener datos por una "familia de fuentes de datos" en una transmisión conciliada.

Este es un ejemplo de cómo filtrar solo el sueño registrado por el dispositivo de seguimiento para el día posterior al 2026-03-03:

Solicitud

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

Respuesta

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

Agrega datos en un período determinado

Usa el rollUp extremo para mostrar el agregado de los datos según una ventana en segundos, en el datetime rango según la hora física de los usuarios (en UTC).

Cuando llames al extremo rollUp, debes proporcionar el cuerpo de la solicitud que representa el período requerido en la hora civil del usuario. Por ejemplo:

Solicitud

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

Respuesta

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

Agrega datos en un solo día o en varios días

Se debe usar el dailyRollUp extremo cuando deseas agregar datos en un solo día o en varios días, lo que se conoce como windowSize. Proporciona el rango de hora civil cerrado-abierto para el intervalo requerido en el cuerpo de la solicitud. Según el tipo de datos, recibirás la suma o el promedio durante el intervalo.

Por ejemplo:

Solicitud

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
}

Respuesta

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

Inserta o actualiza los datos de salud de un usuario

Usa el patch extremo para insertar o actualizar los datos de la app de Fitbit de un usuario.

Este es un ejemplo en el que un usuario registró su grasa corporal en una balanza llamada "HumanScale" de la empresa "Scales R Us". La nueva lectura de grasa corporal del usuario es del 20% para la fecha del 2026-03-10.

Solicitud

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

Respuesta

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

Borra los datos de salud del usuario

Usa el batchDelete extremo para borrar un array de los datos de la app de Fitbit de un usuario.

Este es un ejemplo en el que un usuario registró previamente su grasa corporal en una balanza, pero quiere borrar el registro. Con el user-id y data-point-id de la acción de inserción original:

Solicitud

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

Respuesta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}
Anterior
Bibliotecas cliente
Siguiente
Vínculos universales y de aplicaciones