Develop skin temperature experiences with Google Health API

The Google Health API provides data types that track a user's wrist skin temperature: continuous raw multi-sensor telemetry (skin-temperature-sensors) and daily baseline variation rollups (daily-sleep-temperature-derivations).

Wrist skin temperature measures peripheral thermal dynamics at the skin surface, capturing circadian rhythm patterns, sleep stage transitions, and recovery trends.

Understand the differences between these data types to determine which metrics suit your application.

Supported data types

The API supports the following data types for measuring skin temperature:

Table: Google Health API Skin Temperature data types
Data type Available
operations		 Scope
Skin Temperature Sensors v4beta
dataType: skin-temperature-sensors
filter parameter: skin_temperature_sensors
Record type: Sample

Compatible devices
list .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

For clinical or diagnostic internal organ temperature (such as thermometer measurements), use core-body-temperature.

Read-only requirements

Physiological skin temperature records are populated exclusively by device synchronization and are read-only through the REST API.

The following sections provide technical details and REST representation formats for skin temperature data.

Sensor hardware architectures

Understanding wearable sensor hardware is essential for interpreting temperature data in the Google Health API.

Internal device temperature

Single-sensor devices (such as Pixel Watch 3 and Fitbit Air) feature a single internal temperature sensor positioned near the top of the device casing. This sensor measures Internal Device Temperature (IDT).

Key characteristics of single-sensor devices:

  • Measure internal hardware and ambient temperature conditions rather than direct skin contact.
  • Produce uncompensated raw readings reflecting internal device conditions.
  • Don't support the skin-temperature-sensors endpoint.
  • Support daily-sleep-temperature-derivations using device-level thermal modeling algorithms.

Ambient Compensated Skin Temperature

Dual-sensor devices (Pixel Watch 4 and Pixel Watch 5) feature two temperature sensors:

  • Top sensor (IDT): Measures internal device and ambient temperature.
  • Bottom sensor (Skin contact): Positions directly against the user's wrist skin.

On dual-sensor devices, the bottom sensor measures skin contact temperature to provide Ambient Compensated Skin Temperature (ACST). Only Pixel Watch 4 and Pixel Watch 5 feature this dual-sensor architecture and support the skin-temperature-sensors endpoint. No other devices are supported.

Device compatibility

The availability of skin temperature data types depends on the device's sensor hardware:

  1. skin-temperature-sensors: v4beta Continuous minutely sensor readings capturing paired internal device temperature and on-skin contact temperature from dual-sensor devices. Supported only on dual-sensor devices (Pixel Watch 4 and Pixel Watch 5). Not supported on single-sensor or legacy hardware.
  2. daily-sleep-temperature-derivations: Daily rollups representing nocturnal temperature variations relative to the user's personal baseline. This data type replaces the legacy Fitbit Web API skin temperature endpoint, which reported nightly sleep summaries rather than continuous sensor telemetry. Supported across all Pixel Watch and Fitbit devices equipped with temperature sensors (including Pixel Watch 2 and newer, Fitbit Sense series, Versa series, Charge 4 and newer, Inspire series, Luxe, and Fitbit Air).

For the complete list of supported data types by device, see the Device compatibility guide.

Interpreting temperature values and deltas

Wrist skin temperature measurements reflect peripheral surface dynamics rather than core body temperature. Because skin temperature varies based on environmental conditions and individual baseline physiology, don't evaluate raw Celsius values against clinical thresholds or use them for fever detection.

Working with deltas

Calculate and display relative deltas against baseline rather than raw absolute values.

For daily sleep derivations, calculate the nightly deviation from baseline:

delta = nightlyTemperatureCelsius - baselineTemperatureCelsius

Relative deltas provide consistent, physiologically meaningful insights across sleep sessions. For example, a user whose nightly temperature is 34.07°C with a baseline of 33.95°C has a delta of +0.12°C relative to baseline.

Skin Temperature Sensors

v4beta

The skin-temperature-sensors data type provides continuous minutely raw sensor readings from dual-sensor hardware (Pixel Watch 4 and Pixel Watch 5). Each minute contains paired measurements distinguishing SKIN_TEMPERATURE_SENSOR readings from INTERNAL_DEVICE_TEMPERATURE_SENSOR readings. When working with granular sensor telemetry from skin-temperature-sensors, developers must apply their own algorithms to filter noise, compensate for ambient conditions, and derive actionable metrics.

REST representation example

To query raw sensor telemetry, send a GET request to the dataPoints endpoint:

Request

GET https://health.googleapis.com/v4beta/users/me/dataTypes/skin-temperature-sensors/dataPoints?startTime=2026-07-20T00:00:00Z&endTime=2026-07-20T00:02:00Z
Authorization: Bearer access-token
Accept: application/json

Response

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "displayName": "Google Pixel Watch 4 (45mm)"
        },
        "platform": "FITBIT"
      },
      "skinTemperatureSensors": {
        "sampleTime": {
          "physicalTime": "2026-07-20T00:00:00Z",
          "utcOffset": "3600s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 7,
              "day": 20
            },
            "time": {
              "hours": 1,
              "minutes": 0
            }
          }
        },
        "temperatureCelsius": 34.95,
        "metadata": {
          "measurementLocation": "WRIST",
          "sensorType": "SKIN_TEMPERATURE_SENSOR"
        }
      }
    },
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "displayName": "Google Pixel Watch 4 (45mm)"
        },
        "platform": "FITBIT"
      },
      "skinTemperatureSensors": {
        "sampleTime": {
          "physicalTime": "2026-07-20T00:00:00Z",
          "utcOffset": "3600s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 7,
              "day": 20
            },
            "time": {
              "hours": 1,
              "minutes": 0
            }
          }
        },
        "temperatureCelsius": 31.8,
        "metadata": {
          "measurementLocation": "WRIST",
          "sensorType": "INTERNAL_DEVICE_TEMPERATURE_SENSOR"
        }
      }
    }
  ]
}

Daily Sleep Temperature Derivations

The daily-sleep-temperature-derivations data type reports nightly summary statistics, including the user's average nightly temperature and their personal baseline calculated across previous sleep sessions. This data type replaces the legacy Fitbit Web API skin temperature endpoint, returning daily summary variations rather than continuous intraday telemetry.

Daily sleep temperature derivations are calculated using specialized thermal algorithms and sleep session segmentation, and are not arithmetic averages of raw sensor readings.

REST representation example

To query daily sleep temperature derivations, send a GET request to the dataPoints endpoint:

Request

GET https://health.googleapis.com/v4/users/me/dataTypes/daily-sleep-temperature-derivations/dataPoints?startTime=2026-07-20T00:00:00Z&endTime=2026-07-21T00:00:00Z
Authorization: Bearer access-token
Accept: application/json

Response

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Google Pixel Watch 4 (45mm)"
        },
        "platform": "FITBIT"
      },
      "dailySleepTemperatureDerivations": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 20
        },
        "nightlyTemperatureCelsius": 34.12,
        "baselineTemperatureCelsius": 33.95,
        "relativeNightlyStddev30dCelsius": 0.23
      }
    }
  ]
}

Guidelines

When integrating skin temperature data into your application, use these guidelines:

  • Visualize user temperature changes as relative deviations from personal baseline rather than raw Celsius values.
  • Verify that the user is recording with a supported dual-sensor device (Pixel Watch 4 or Pixel Watch 5) when querying skin-temperature-sensors, or handle empty data responses gracefully. To check a user's paired device model, see the Find device information example in the Endpoints guide.
  • Combine nightly temperature variations with sleep session data to provide contextual recovery insights.
  • Apply custom analytical algorithms when working with granular skin-temperature-sensors telemetry, and avoid calculating averages to reproduce nightly baselines because daily derivations rely on specialized thermal models and sleep tracking.
  • Clearly explain why temperature metrics are collected and why the health_metrics_and_measurements scope is required before prompting users for authorization.
Previous
生命体征
Next
锻炼