> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spikeapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```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
## OpenAPI
````yaml get /queries/timeseries
openapi: 3.1.0
info:
title: Application user API
version: 3.0.2
servers:
- url: https://app-api.spikeapi.com/v3
security: []
paths:
/queries/timeseries:
get:
tags:
- Queries / Time Series
summary: Time Series
description: >+
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
operationId: getQueriesTimeseries
parameters:
- description: Start time of the query range in UTC, inclusive
example: '2006-01-02T15:04:05'
explode: false
in: query
name: from_timestamp
schema:
description: Start time of the query range in UTC, inclusive
examples:
- '2006-01-02T15:04:05'
- '2006-01-02T15:04:05Z'
format: date-time
- description: End time of the query range in UTC, non-inclusive
example: '2006-01-02T15:04:05'
explode: false
in: query
name: to_timestamp
schema:
description: End time of the query range in UTC, non-inclusive
examples:
- '2006-01-02T15:04:05'
- '2006-01-02T15:04:05Z'
format: date-time
- description: The metric you want to query
explode: false
in: query
name: metric
required: true
schema:
description: The metric you want to query
enum:
- 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
type: string
- explode: false
in: query
name: providers
schema:
items:
enum:
- strava
- health_connect
- fitbit
- garmin
- huawei
- dexcom
- whoop
- withings
- suunto
- apple
- freestyle_libre
- oura
- polar
- coros
- ultrahuman
- samsung_health_data
- luna
- map_my_fitness
- application
type: string
type: array
- description: Whether to include the record IDs in the response
explode: false
in: query
name: include_record_ids
schema:
description: Whether to include the record IDs in the response
type: boolean
- description: Method to merge data
explode: false
in: query
name: merge_method
schema:
description: Method to merge data
enum:
- 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
type: string
- description: Device types to include
explode: false
in: query
name: device_types
schema:
description: Device types to include
items:
enum:
- unknown
- phone
- watch
- scale
- ring
- head_mounted
- fitness_band
- chest_strap
- smart_display
- accessory
type: string
type: array
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeseriesMergedQueryOutput'
description: OK
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad Request
'401':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Unauthorized
'404':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Not Found
'422':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Unprocessable Entity
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal Server Error
security:
- bearer: []
components:
schemas:
TimeseriesMergedQueryOutput:
additionalProperties: false
properties:
device_types:
description: Device types involved for these timeseries
items:
enum:
- unknown
- phone
- watch
- scale
- ring
- head_mounted
- fitness_band
- chest_strap
- smart_display
- accessory
type: string
type: array
durations:
description: Duration of each timeseries entry in milliseconds
items:
format: int64
type: integer
type:
- array
- 'null'
from_timestamp:
examples:
- '2006-01-02T00:00:00Z'
format: date-time
type: string
metric:
description: The metric type for these timeseries
enum:
- 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
type: string
offsets:
description: Millisecond offsets from the start_at timestamp
items:
format: int64
type: integer
type:
- array
- 'null'
provider_sources:
description: Provider sources involved for these timeseries
items:
enum:
- apple_healthkit_sample
- apple_healthkit_activity
- apple_healthkit_sample_category
- apple_healthkit_sleep_aggregation
- apple_healthkit_statistics
- apple_healthkit_characteristics
- apple_healthkit_ecgs
- apple_healthkit_mindfulness
- health_connect_record
- health_connect_activity
- health_connect_mindfulness_session
- health_connect_aggregation
- fitbit_activities_list
- fitbit_activities_daily_summary
- fitbit_activities_daily_summary_activity
- fitbit_activity_heart_intraday
- fitbit_activity_steps_intraday
- fitbit_activity_distance_intraday
- fitbit_activity_calories_intraday
- fitbit_hrv_summary
- fitbit_hrv_intraday
- fitbit_vo2max_summary
- fitbit_sleep_summary
- fitbit_activity_tcx
- fitbit_br_summary
- fitbit_br_intraday
- fitbit_spo2_summary
- fitbit_spo2_intraday
- fitbit_core_temperature_summary
- fitbit_skin_temperature_summary
- fitbit_ecg
- fitbit_body_log_fat
- fitbit_body_log_weight
- garmin_wellness_epochs
- garmin_wellness_dailies
- garmin_wellness_activities
- garmin_wellness_activity_details
- garmin_wellness_sleep
- garmin_wellness_activity_file
- garmin_wellness_hrv
- garmin_wellness_user_metrics
- garmin_wellness_body_comps
- garmin_wellness_blood_pressures
- garmin_wellness_stress_details
- garmin_wellness_skin_temperature
- oura_user_collection_daily_activity_document
- oura_user_collection_sleep_document
- oura_user_collection_workout_document
- oura_user_collection_daily_spo2_document
- oura_user_collection_vo2_max
- oura_user_collection_hr_document
- oura_user_collection_session_document
- oura_personal_info
- oura_user_collection_daily_sleep
- polar_continuous_heart_rate_by_date
- polar_exercise
- polar_exercise_fit_file
- polar_sleep_available
- polar_activity_transaction
- polar_activity_transaction_steps
- polar_sleep_by_date
- polar_nightly_recharge
- polar_biosensing_spo2
- polar_biosensing_body_temperature
- polar_biosensing_skin_temperature
- polar_physical_information
- polar_biosensing_ecg
- polar_user_info
- strava_activity
- suunto_workout_summary
- suunto_workout_fit_file
- suunto_activity_samples
- suunto_activity_daily_summary
- suunto_sleep_samples
- whoop_cycle
- whoop_cycle_recovery
- whoop_activity_sleep
- whoop_activity_workout
- whoop_user_body_measurement
- withings_sleep_summary
- withings_sleep_get
- withings_measure_workouts
- withings_measure_activity
- withings_measure_meas
- withings_measure_activity_intraday
- withings_heart_list
- withings_heart_get
- withings_sleep_combined
- wahoo_workout_summary
- wahoo_workout_fit_file
- huawei_activity_record
- huawei_sampling_data_daily_activity_summary
- huawei_sampling_data_details
- huawei_sampling_data_statistics
- huawei_sampling_data_daily
- huawei_health_record
- huawei_sampling_data_latest
- ultrahuman_heartrate_metrics
- ultrahuman_hrv_metrics
- ultrahuman_temp_metrics
- ultrahuman_heartrate_resting_metrics
- ultrahuman_steps_metrics
- ultrahuman_vo2max_metrics
- ultrahuman_glucose_metrics
- ultrahuman_sleep_metrics
- coros_workout
- coros_workout_fit_file
- coros_daily_record
- coros_daily_record_sleep
- samsung_health_data_aggregation
- samsung_health_data_samples
- samsung_health_data_user_profile
- samsung_health_data_exercise
- samsung_health_data_sleep
- dexcom_egvs
- freestyle_libre_glucose
- luna_sleep
- omron_us_blood_pressure
- omron_us_hourly_activity
- omron_us_weight
- omron_us_temperature
- omron_us_oxygen
- omron_eu_blood_pressure
- omron_eu_hourly_activity
- omron_eu_weight
- omron_eu_temperature
- omron_eu_oxygen
- map_my_fitness_workout
- compat_apple_healthkit_entry
- compat_health_connect_entry
type: string
type: array
providers:
description: Providers involved for these timeseries
items:
description: Provider slugs
examples:
- strava
- omron_eu
- omron_us
- health_connect
- fitbit
- garmin
- huawei
- dexcom
- whoop
- withings
- suunto
- apple
- freestyle_libre
- oura
- polar
- coros
- ultrahuman
- samsung_health_data
- luna
type: string
type: array
record_ids:
description: IDs of the records containing these timeseries
items:
description: Unique identifier for a record.
examples:
- 12345678-1234-abcd-4321-abcdef123456
format: uuid
type: string
type:
- array
- 'null'
to_timestamp:
examples:
- '2006-01-02T00:00:00Z'
format: date-time
type: string
values:
description: The actual metric values for each timeseries entry
items:
$ref: '#/components/schemas/MetricValue'
type:
- array
- 'null'
required:
- metric
type: object
ErrorModel:
additionalProperties: false
properties:
detail:
description: >-
A human-readable explanation specific to this occurrence of the
problem.
examples:
- Property foo is required but is missing.
type: string
errors:
description: Optional list of individual error details
items:
$ref: '#/components/schemas/ErrorDetail'
type:
- array
- 'null'
instance:
description: >-
A URI reference that identifies the specific occurrence of the
problem.
examples:
- https://example.com/error-log/abc123
format: uri
type: string
status:
description: HTTP status code
examples:
- 400
format: int64
type: integer
title:
description: >-
A short, human-readable summary of the problem type. This value
should not change between occurrences of the error.
examples:
- Bad Request
type: string
type:
default: about:blank
description: A URI reference to human-readable documentation for the error.
examples:
- https://example.com/errors/example
format: uri
type: string
type: object
MetricValue:
additionalProperties: false
type: object
ErrorDetail:
additionalProperties: false
properties:
location:
description: >-
Where the error occurred, e.g. 'body.items[3].tags' or
'path.thing-id'
type: string
message:
description: Error message text
type: string
value:
description: The value at the given location
type: object
securitySchemes:
bearer:
bearerFormat: JWT
scheme: bearer
type: http
````