Extremos

En esta página, se proporciona una descripción general de las convenciones de la API de REST, junto con un índice de 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/paginación), pero también se usa para operaciones DELETE.

  • Posició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 (strings, ints, enums) y campos repetidos.

Para obtener una lista detallada de los formatos de filtro, las referencias de campos, las reglas de validación y los ejemplos, consulta la guía de datos de filtros.

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í. Por lo general, se usa para las operaciones POST, PATCH y PUT.

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

Para obtener lineamientos detallados sobre los tamaños de las ventanas de resumen, las reglas de agrupamiento en buckets y los ejemplos de agregación, consulta la guía de datos agregados.

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 que cumple con la AIP-134 o una operación PATCH, se usan ambos. La URL contiene el nombre del recurso, el cuerpo contiene los datos actualizados del recurso y un parámetro de consulta (por lo general, update_mask) especifica qué campos se deben cambiar.

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

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

Diferencias clave de un vistazo

Función Parámetros de búsqueda Cuerpo de la solicitud
Orientación sobre AIP Se usa para operaciones de búsqueda, filtrado y lectura. Se usa para operaciones de escritura.
Visibilidad Visible en el historial de navegación y en los registros del servidor. Se oculta de la URL.
Complejidad Se limita a estructuras planas o repetidas. Admite objetos JSON con un nivel de anidamiento profundo.
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-9999
  • No se aplican las restricciones de fecha de inicio que implica el estándar ISO-8601 ni ninguna otra época.

Encabezados

Para ejecutar los extremos de la API de Google Health, se deben 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 otorga su consentimiento a través de Google OAuth 2.0, la respuesta del token no contiene el ID de usuario de Fitbit ni de Google. Llama al extremo getIdentity de inmediato después de intercambiar el código de autorización para recuperar legacyUserId y healthUserId, y verificar que la Cuenta de Google del usuario esté vinculada a Google Health. Si la cuenta aún no está vinculada, getIdentity devuelve 400 Bad Request con el motivo ACCOUNT_NOT_LINKED (consulta Cómo controlar las Cuentas de Google no vinculadas).

Por ejemplo:

Solicitud

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

Respuesta (200 OK)

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

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

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

Usa el extremo list para un tipo de datos específico con el objetivo de obtener datos intradía o detallados 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"
}

Obtén una vista conciliada de los datos de intervalos

Para recuperar datos de intervalos sin registros superpuestos ni conflictos multidispositivo, llama al extremo reconcile. El extremo de conciliación anula automáticamente los intervalos superpuestos en los lotes de sincronización y en varios dispositivos de grabación, lo que devuelve un flujo continuo y confiable adecuado para renderizar cronogramas de actividad y calcular duraciones.

Para obtener información sobre por qué los dispositivos conectados producen intervalos superpuestos y una comparación operativa entre list y reconcile, consulta la guía de administración de datos.

En el siguiente ejemplo, se compara la respuesta de list (que devuelve ambos registros superpuestos) con la de reconcile (que resuelve el conflicto devolviendo el registro de autoridad) para un usuario con dos sesiones de ejercicio superpuestas:

Lista sin procesar

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

Conciliado

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

La conciliación resuelve las sesiones en conflicto desduplicando y seleccionando el registro autorizado en lugar de sintetizar una unión de tiempo artificial (como 11:00:00Z a 11:50:00Z). La respuesta conciliada devuelve el dato ganador (7797422996486764704) con su intervalo registrado original (11:20:00Z a 11:50:00Z), lo que preserva la integridad de la telemetría y las métricas medidas de esa sesión.

Filtra datos

Para recuperar subconjuntos específicos de registros de datos que coincidan con criterios como un intervalo de tiempo, una fecha o una hora de observación, usa el extremo list o reconcile con un parámetro filter.

Para obtener lineamientos detallados, reglas de formato, errores de validación y ejemplos de consultas, consulta la guía para filtrar datos.

Filtrar por familia de fuentes de datos

Para aislar o agregar datos de tipos específicos de fuentes (por ejemplo, dispositivos wearables físicos en comparación con entradas manuales), usa el parámetro dataSourceFamily.

Para obtener lineamientos detallados, familias admitidas y ejemplos de solicitudes y respuestas para reconcile, rollUp y dailyRollUp, consulta Filtra por familia de fuentes de datos en la guía Filtra datos.

Filtra los datos por una hora de inicio civil del intervalo

Usa el extremo list con un parámetro filter para filtrar los 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 los datos por la hora física de una observación de muestra

Usa el extremo list con un parámetro filter para filtrar los datos por el tiempo físico de observación de la 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/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": ""
}

Filtra y agrega por familia de fuentes de datos

Una familia de fuentes de datos es una agrupación lógica de fuentes de datos (como relojes inteligentes, apps para dispositivos móviles o entradas manuales). Te permite aislar o agregar datos de tipos específicos de fuentes (por ejemplo, dispositivos wearables físicos en comparación con entradas manuales).

Los extremos reconcile, rollUp y dailyRollUp admiten el parámetro dataSourceFamily. El mecanismo de transferencia depende del extremo:

Extremo (método HTTP) Mecanismos
reconcile (GET) Pasa dataSourceFamily como un parámetro de consulta de URL.
rollUp (POST) Pasa dataSourceFamily como un campo en el cuerpo de la solicitud JSON.
dailyRollUp (POST) Pasa dataSourceFamily como un campo en el cuerpo de la solicitud JSON.

Familias de fuentes de datos compatibles

En la siguiente tabla, se describen los valores de dataSourceFamily admitidos:

Opción Descripción
users/me/dataSourceFamilies/all-sources Es el valor predeterminado. Devuelve datos conciliados en todas las fuentes de datos de origen (1P) y de terceros (3P) registradas. Con esta opción, se devolverán los datos de app de terceros (como los pasos del reloj inteligente, los pasos de las apps de terceros, los pasos del teléfono celular y los pasos manuales).
users/me/dataSourceFamilies/google-wearables Incluye los datos registrados por los dispositivos de monitoreo de Google y Fitbit (como los monitores de Fitbit y el Pixel Watch). Se excluyen los datos registrados manualmente y los datos estimados por el teléfono. Usa esta opción cuando tu integración requiera telemetría de sensores sin procesar registrada directamente por el hardware del wearable.
users/me/dataSourceFamilies/google-sources Incluye fuentes propias de Google y Fitbit. Esto incluye los registros de dispositivos de monitoreo físico, los datos de Health Connect y cualquier entrada manual registrada a través de apps propias (como la app de Fitbit o Google Fit).

Para obtener un flujo de datos conciliado de una familia de fuentes de datos específica, llama al extremo reconcile con el parámetro de consulta dataSourceFamily.

Por ejemplo, la siguiente solicitud GET recupera el sueño registrado por el monitor para el día posterior al 3 de marzo de 2026:

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

Para agregar datos agregados en un tamaño de ventana específico restringido a una familia de fuentes de datos en particular, llama al endpoint rollUp y pasa el campo dataSourceFamily en el cuerpo de la solicitud JSON.

La siguiente solicitud POST consulta los recuentos de pasos de caminata intradía en intervalos por hora (3600s), agregados exclusivamente desde dispositivos wearable:

Solicitud

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

Respuesta

{
  "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 datos diarios de una familia de fuentes específica, llama al extremo dailyRollUp y pasa el campo dataSourceFamily en el cuerpo de la solicitud.

Por ejemplo, la siguiente solicitud calcula los resúmenes diarios de los pasos del usuario, incluidas todas las fuentes propias de Google y Fitbit (dispositivos wearable y entradas manuales):

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

Respuesta

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

Agrega datos en un rango de tiempo

Usa el extremo rollUp para devolver el agregado de datos según un período en segundos (windowSize) en un rango de datetime en la hora física del usuario (en UTC).

Cuando llames al extremo rollUp, proporciona el cuerpo de la solicitud que representa el tiempo cerrado-abierto requerido range y windowSize (al menos "1s"). Para obtener lineamientos detallados sobre los requisitos de windowSize, la alineación de la resolución de almacenamiento, las reglas de agrupamiento en buckets y los ejemplos de solicitudes y respuestas, consulta Agrega datos en intervalos de tiempo físicos en la guía de datos agregados.

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

Usa el extremo dailyRollUp para agregar datos de un solo día o de varios días (windowSizeDays). Proporciona la hora civil de cierre y apertura range para el intervalo requerido en el cuerpo de la solicitud. Según el tipo de datos, el extremo devuelve la suma o el promedio de cada ventana.

Para obtener detalles sobre el comportamiento de la agregación diaria, el manejo de la hora civil, los límites de rango por solicitud y los ejemplos de solicitud y respuesta, consulta Agrega datos en días calendario en la guía de datos agregados.

Actualiza los datos de salud de un usuario

Usa el extremo patch para actualizar los datos de salud de un usuario.

El extremo patch actualiza un registro existente según el identificador especificado en la URL de la solicitud. Proporciona el identificador de un dato insertado anteriormente. La API reemplaza el registro existente.

Las marcas de tiempo del intervalo de un dato (startTime y endTime) también las puede actualizar el propietario del registro o se pueden propagar desde plataformas ascendentes, como Health Connect. Para obtener detalles sobre la mutabilidad de las marcas de tiempo, consulta la guía de administración de datos. Para ver un ejemplo de actualización de marcas de tiempo de intervalo, consulta Actualiza las marcas de tiempo de intervalo para los datos existentes.

Cuándo usar el identificador de datos

El identificador de datos es esencial en las siguientes situaciones:

  • Actualizaciones segmentadas: Para actualizar una medición específica, proporciona su identificador en la solicitud patch.
  • Borrado: Conservar el identificador permite que tu aplicación borre el registro más adelante con el extremo batchDelete.

Este es un ejemplo en el que un usuario actualiza su lectura de grasa corporal en una báscula llamada "HumanScale" de la empresa "Scales R Us". La nueva lectura de grasa corporal del usuario es del 20% para la fecha 10 de marzo de 2026:

Solicitud

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

Respuesta

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

Actualiza las marcas de tiempo de los intervalos de los datos existentes

Para actualizar las marcas de tiempo del intervalo (startTime y endTime en las cargas útiles de JSON de REST, o start_time y end_time en gRPC) de un dato existente, envía una solicitud PATCH al URI del recurso del dato. Solo el creador o propietario original de un registro puede modificar sus campos. Las aplicaciones no pueden editar los datos que no crearon.

Para obtener información sobre la mutabilidad de las marcas de tiempo, las actualizaciones ascendentes de Health Connect y las implicaciones del almacenamiento en caché, consulta la guía de administración de datos.

En el siguiente ejemplo, se muestra una aplicación propietaria que actualiza las marcas de tiempo de intervalo de un registro de hidratación existente con el extremo patch:

Solicitud

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

Respuesta

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

Registra un alimento

Para registrar un alimento, envía una solicitud POST al extremo nutrition-log dataPoints. El cuerpo de la solicitud contiene un DataPoint con un objeto nutritionLog. Para obtener más información, consulta la guía de nutrición.

Por ejemplo:

Solicitud

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

Respuesta

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

Borra los datos de salud del usuario

Usa el método batchDelete para borrar un array de los datos de 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. Usa el user-id y el 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/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Respuesta

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

Cómo encontrar información de un dispositivo

Usa el extremo list para recuperar la lista de dispositivos vinculados a la cuenta de un usuario. Esto incluye la información del modelo del dispositivo (deviceVersion) y la última vez que se sincronizó con la app para dispositivos móviles de Google Health (lastSyncTime).

La información de configuración y sincronización de la lista es útil para solucionar problemas de sincronización o recuperar datos históricos desde la última sincronización.

Por ejemplo:

Solicitud

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

Respuesta

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

Consulta datos históricos

Uno de los beneficios principales de la API de Google Health es la capacidad de hacer un seguimiento del rendimiento de un usuario y supervisar sus signos vitales durante períodos prolongados. Puedes consultar los datos de un usuario desde el momento en que se registraron. La API no impone limitaciones ni restricciones en la cantidad de datos históricos que tu aplicación puede consumir.

Sin embargo, la consulta de datos históricos sigue regida por los límites de frecuencia estándar. Para administrar la estabilidad del sistema y evitar cargas útiles excesivas, la API de Google Health usa la paginación automática con tamaños de página específicos de los extremos. Ten en cuenta los siguientes límites y comportamientos:

  • Paginación automática: Si consultas un período largo de datos, la API solo devolverá la primera página de resultados hasta el límite de tamaño de página para ese extremo, junto con un nextPageToken. Debes usar el nextPageToken para solicitar las páginas posteriores.
  • Tamaños de página variables: Los límites máximos dependen del extremo y del tipo de datos. Para la mayoría de los tipos de datos, los tamaños de página tienen un límite máximo de 10,000. Sin embargo, para ciertos tipos de datos, como exercise y sleep, el tamaño de página predeterminado y máximo tiene un límite de 25. Por ejemplo, si un cliente solicita todos los datos de sueño de los últimos 10 años, la API seguirá mostrando solo 25 sesiones de sueño en la primera página.
  • Restricciones del período de resumen: Para los extremos de resumen y agregación de datos (como rollUp y dailyRollUp), los períodos de consulta están restringidos según el tipo de datos:
    • Un rango máximo de 14 días para calories-in-heart-rate-zone, heart-rate, active-minutes y total-calories.
    • Un rango máximo de 90 días para todos los demás tipos de datos de resumen

Según el volumen de datos históricos que necesite tu aplicación, para recuperar todo el conjunto de datos, se requerirá paginar las páginas de forma secuencial. Ten esto en cuenta cuando diseñes el proceso de sincronización de datos de tu aplicación.

Para garantizar un rendimiento óptimo y evitar errores de la API, sigue estos lineamientos cuando consultes datos históricos:

Sincronización de datos por fases (carga en caliente frente a carga en frío)

  • Carga inicial "activa": Recupera y renderiza solo los datos más recientes de 7 a 14 días durante la secuencia de carga principal. Esto garantiza que los usuarios vean los datos de inmediato sin esperar a que se ejecuten consultas prolongadas.
  • Carga "en frío" en segundo plano: Delega la recuperación de datos históricos más antiguos a una cola asíncrona de menor prioridad o a un proceso en segundo plano después de que se renderice la IU principal.

División de consultas en fragmentos para la agregación

  • Debido a que los extremos de resumen y resumen diario aplican un límite máximo de período (14 o 90 días, según el tipo de datos), debes desglosar las consultas de agregación histórica grandes en intervalos secuenciales más pequeños dentro de estos límites.
  • Agrupa o secuencia estas subconsultas de forma segura para respetar los límites de simultaneidad y mantener indicadores de progreso de la IU estables.

Aprovecha los resúmenes agregados previamente

Reestructura los paneles de descripción general y los gráficos de tendencias para usar extremos de resumen preagregados (como DailyRollUpDataPoints). Esto reducirá drásticamente la sobrecarga de procesamiento en el backend y el tiempo de transferencia de red al cliente.

Manejo de errores resiliente (reintentos inteligentes)

  • Implementa un manejo estricto de la retirada exponencial cuando se alcancen los límites de frecuencia (429 Too Many Requests) y los tiempos de espera de la puerta de enlace del servidor (504 Gateway Timeout). Nunca reintentes de inmediato las cargas útiles grandes que fallaron. Los reintentos instantáneos multiplican la congestión del backend y agravan la degradación del sistema.
Anterior
Bibliotecas cliente
Siguiente
Filtros