Sign in

v1

latestOpenAPI 3.1.02026-07-136587849.3 KB
Queries / Time Series

Time Series

This endpoint returns a time series for a given metric with automatic merge strategy selection. The system chooses the optimal merge method based on metric characteristics to ensure the best data quality without manual configuration.

Request Example

{
  "from_timestamp": "2024-01-01T00:00:00Z",
  "to_timestamp": "2024-01-02T00:00:00Z",
  "metric": "heartrate"
}

Response Example

{
  "metric": "heartrate",
  "start_at": "2024-01-01T00:00:00Z",
  "offsets": [0, 60000, 120000],
  "durations": [60000, 60000, 60000],
  "values": [100, 150, 200],
  "providers": ["garmin"]
}
<Note> The arrays `offsets`, `durations`, and `values` will all be of the same length. This alignment is crucial for interpreting the data correctly. </Note>

Overriding the Default Merge Method

To override the default merge strategy, use the merge_method parameter.

<Note> The default merge method is automatically selected based on the metric type and provides optimal data quality for most use cases. Only override the default if you have specific requirements that cannot be met by the automatic selection. This parameter is intended for advanced users who understand the implications of different merge strategies. </Note>

Source Selection Methods

Selects data from a single best provider source based on criteria like coverage, granularity, or priority. Only one source contributes to the final result, ensuring consistency but potentially losing data from other sources.

  • select_best_weighted_source: Best weighted coverage score mix of time coverage and data point density

  • select_highest_coverage_source: Highest total time coverage (sum of all entry durations)

  • select_most_granular_source: Most data points (highest entry count)

  • select_highest_priority_source_type: Sample > Intraday > Summary > Activity priority, then weighted coverage

Coverage Optimization Methods

Maximizes time coverage by selecting non-overlapping entries from multiple sources. Prioritizes filling time gaps while avoiding overlaps, using interval scheduling algorithms.

  • merge_maximize_coverage: Weighted interval scheduling to maximize total time coverage

  • merge_maximize_granularity: Source with most data points, then greedy interval scheduling

  • merge_maximize_weighted_coverage: Source with best weighted coverage score, then greedy interval scheduling

Sample Merging Methods

Combines all sample data points, resolving conflicts at identical timestamps by selecting the source with the most total entries. Preserves all available data while handling timestamp collisions.

  • merge_all_samples: All zero-duration samples, conflicts resolved by source with most total entries
get/queries/timeseries

Query parameters

from_timestampstring date-time

Start time of the query range in UTC, inclusive

Example:2006-01-02T15:04:05

Start time of the query range in UTC, inclusive

to_timestampstring date-time

End time of the query range in UTC, non-inclusive

Example:2006-01-02T15:04:05

End time of the query range in UTC, non-inclusive

metric'heartrate_max' | 'heartrate_min' | 'heartrate_zone0_duration' | 'heartrate_zone1_duration' | 'heartrate_zone2_duration' | 'heartrate_zone3_duration' | 'heartrate_zone4_duration' | 'heartrate_zone5_duration' | 'heartrate' | 'heartrate_resting' | 'heartrate_resting_min' | 'heartrate_resting_max' | 'hrv_rmssd' | 'hrv_sdnn' | 'elevation_max' | 'elevation_min' | 'elevation_gain' | 'elevation_loss' | 'ascent' | 'descent' | 'calories_burned_active' | 'calories_burned_basal' | 'calories_burned' | 'calories_intake' | 'steps' | 'floors_climbed' | 'distance' | 'distance_walking' | 'distance_cycling' | 'distance_running' | 'distance_wheelchair' | 'distance_swimming' | 'speed' | 'speed_max' | 'speed_min' | 'air_temperature_max' | 'air_temperature' | 'air_temperature_min' | 'spo2' | 'spo2_max' | 'spo2_min' | 'breathing_rate' | 'breathing_rate_min' | 'breathing_rate_max' | 'longitude' | 'latitude' | 'elevation' | 'duration_active' | 'swimming_lengths' | 'swimming_distance_per_stroke' | 'sleep_efficiency' | 'sleep_duration' | 'sleep_duration_deep' | 'sleep_duration_light' | 'sleep_duration_rem' | 'sleep_duration_awake' | 'bedtime_duration' | 'sleep_interruptions' | 'sleep_duration_nap' | 'sleep_score' | 'sleep_breathing_rate' | 'sleep_breathing_rate_min' | 'sleep_breathing_rate_max' | 'sleep_latency' | 'wakeup_latency' | 'cadence' | 'cadence_min' | 'cadence_max' | 'pace' | 'body_mass_index' | 'weight' | 'height' | 'vo2max' | 'body_temperature' | 'body_temperature_max' | 'body_temperature_min' | 'basal_body_temperature' | 'basal_body_temperature_max' | 'basal_body_temperature_min' | 'skin_temperature' | 'skin_temperature_max' | 'skin_temperature_min' | 'sleep_skin_temperature_deviation' | 'ecg_voltage' | 'ecg_rri' | 'body_fat' | 'body_fat_min' | 'body_fat_max' | 'blood_pressure_systolic' | 'blood_pressure_systolic_min' | 'blood_pressure_systolic_max' | 'blood_pressure_diastolic' | 'blood_pressure_diastolic_min' | 'blood_pressure_diastolic_max' | 'body_bone_mass' | 'glucose' | 'power' | 'power_max' | 'duration_low_intensity' | 'duration_moderate_intensity' | 'duration_high_intensity' required

The metric you want to query

The metric you want to query

providersstring[]
include_record_idsboolean

Whether to include the record IDs in the response

Whether to include the record IDs in the response

merge_method'select_best_weighted_source' | 'select_highest_coverage_source' | 'select_most_granular_source' | 'select_highest_priority_source_type' | 'merge_maximize_coverage' | 'merge_maximize_granularity' | 'merge_maximize_weighted_coverage' | 'merge_all_samples'

Method to merge data

Method to merge data

device_typesstring[]

Device types to include

Device types to include

Response

OK

device_typesstring[]

Device types involved for these timeseries

durationsinteger[] nullable

Duration of each timeseries entry in milliseconds

from_timestampstring date-time
metric'heartrate_max' | 'heartrate_min' | 'heartrate_zone0_duration' | 'heartrate_zone1_duration' | 'heartrate_zone2_duration' | 'heartrate_zone3_duration' | 'heartrate_zone4_duration' | 'heartrate_zone5_duration' | 'heartrate' | 'heartrate_resting' | 'heartrate_resting_min' | 'heartrate_resting_max' | 'hrv_rmssd' | 'hrv_sdnn' | 'elevation_max' | 'elevation_min' | 'elevation_gain' | 'elevation_loss' | 'ascent' | 'descent' | 'calories_burned_active' | 'calories_burned_basal' | 'calories_burned' | 'calories_intake' | 'steps' | 'floors_climbed' | 'distance' | 'distance_walking' | 'distance_cycling' | 'distance_running' | 'distance_wheelchair' | 'distance_swimming' | 'speed' | 'speed_max' | 'speed_min' | 'air_temperature_max' | 'air_temperature' | 'air_temperature_min' | 'spo2' | 'spo2_max' | 'spo2_min' | 'breathing_rate' | 'breathing_rate_min' | 'breathing_rate_max' | 'longitude' | 'latitude' | 'elevation' | 'duration_active' | 'swimming_lengths' | 'swimming_distance_per_stroke' | 'sleep_efficiency' | 'sleep_duration' | 'sleep_duration_deep' | 'sleep_duration_light' | 'sleep_duration_rem' | 'sleep_duration_awake' | 'bedtime_duration' | 'sleep_interruptions' | 'sleep_duration_nap' | 'sleep_score' | 'sleep_breathing_rate' | 'sleep_breathing_rate_min' | 'sleep_breathing_rate_max' | 'sleep_latency' | 'wakeup_latency' | 'cadence' | 'cadence_min' | 'cadence_max' | 'pace' | 'body_mass_index' | 'weight' | 'height' | 'vo2max' | 'body_temperature' | 'body_temperature_max' | 'body_temperature_min' | 'basal_body_temperature' | 'basal_body_temperature_max' | 'basal_body_temperature_min' | 'skin_temperature' | 'skin_temperature_max' | 'skin_temperature_min' | 'sleep_skin_temperature_deviation' | 'ecg_voltage' | 'ecg_rri' | 'body_fat' | 'body_fat_min' | 'body_fat_max' | 'blood_pressure_systolic' | 'blood_pressure_systolic_min' | 'blood_pressure_systolic_max' | 'blood_pressure_diastolic' | 'blood_pressure_diastolic_min' | 'blood_pressure_diastolic_max' | 'body_bone_mass' | 'glucose' | 'power' | 'power_max' | 'duration_low_intensity' | 'duration_moderate_intensity' | 'duration_high_intensity' required

The metric type for these timeseries

offsetsinteger[] nullable

Millisecond offsets from the start_at timestamp

provider_sourcesstring[]

Provider sources involved for these timeseries

providersstring[]

Providers involved for these timeseries

record_idsstring[] nullable

IDs of the records containing these timeseries

to_timestampstring date-time
valuesMetricValue[] nullable

The actual metric values for each timeseries entry

Example response

{
  "from_timestamp": "2006-01-02T00:00:00Z",
  "providers": [
    "strava"
  ],
  "record_ids": [
    "12345678-1234-abcd-4321-abcdef123456"
  ],
  "to_timestamp": "2006-01-02T00:00:00Z"
}