--- title: "Time Series" method: GET path: "/queries/timeseries" tags: ["Queries / Time Series"] --- # Time Series `GET /queries/timeseries` 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 ```json { "from_timestamp": "2024-01-01T00:00:00Z", "to_timestamp": "2024-01-02T00:00:00Z", "metric": "heartrate" } ``` ## Response Example ```json { "metric": "heartrate", "start_at": "2024-01-01T00:00:00Z", "offsets": [0, 60000, 120000], "durations": [60000, 60000, 60000], "values": [100, 150, 200], "providers": ["garmin"] } ``` The arrays `offsets`, `durations`, and `values` will all be of the same length. This alignment is crucial for interpreting the data correctly. ## Overriding the Default Merge Method To override the default merge strategy, use the `merge_method` parameter. 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. ### 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 ## Query parameters - `from_timestamp` string, date-time — Start time of the query range in UTC, inclusive - `to_timestamp` string, date-time — 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 - `providers` string[] - `include_record_ids` boolean — 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 - `device_types` string[] — Device types to include ## Response `200` OK - TimeseriesMergedQueryOutput - `device_types` string[] — Device types involved for these timeseries - `durations` integer[], nullable — Duration of each timeseries entry in milliseconds - `from_timestamp` string, 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 - `offsets` integer[], nullable — Millisecond offsets from the start_at timestamp - `provider_sources` string[] — Provider sources involved for these timeseries - `providers` string[] — Providers involved for these timeseries - `record_ids` string[], nullable — IDs of the records containing these timeseries - `to_timestamp` string, date-time - `values` MetricValue[], nullable — The actual metric values for each timeseries entry ## Other responses - `400` — Bad Request - `401` — Unauthorized - `404` — Not Found - `422` — Unprocessable Entity - `500` — Internal Server Error --- [API](https://skmtc.dev/spikeapi/apis/application-user-api.md) · [All operations](https://skmtc.dev/spikeapi/apis/application-user-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spikeapi/application-user-api/revisions/637338fb0c9d/schema)