Query Options Overview

Choosing the Right Query Option

Comparison of Query Options for Developers

Querying Data

SpikeAPI

Get started with Spike API - your gateway to health and fitness data integration

Introduction

Spike API is designed for developers who want to seamlessly connect their applications to user health data from multiple providers. Below is a high-level guide to the main components of the integration process. Each section links to detailed documentation.

Overview

Authentication

Provider Integration

To receive data updates, configure a webhook endpoint via the admin console. After each data update from the provider, a webhook event will be sent to your endpoint.

Webhooks

Delete Integration

User Information

User Properties

### List Provider Records

Query provider records with metrics, optionally filtering by providers.

This endpoint allows you to query provider records with support for:
- Filtering by UTC timestamp range and providers.
- Including provider-specific metrics in the response.

The response includes records with raw data from providers transformed into the unified data model, each possibly including:
- base information (start, end, duration, user time offset, input method, source provider, etc.)
- metrics (base and provider-specific)
- activity information such as activity ID, type, and tags
- activity breakdown into laps, sessions, etc.
- sleeps with sample data

All timestamps in both request and response are in the UTC timezone.


List Provider Records

### Query a Provider Record by ID

Query a single provider record with metrics by ID.

This endpoint allows you to query for the provider record with support for:
- Including sample data based on time series in the response.
- Including provider-specific metrics in the response.

The response includes a single record with raw data from the provider transformed into the unified data model, possibly including:
- base information (start, end, duration, user time offset, input method, source provider, etc.)
- metrics (base and provider-specific)
- activity information such as activity ID, type, and tags
- activity breakdown into laps, sessions, etc. with related sample data
- sleep with sample data

All timestamps in the response are in the UTC timezone.


Get Provider Record

### Sleep Stages

Sleep stages represent the different phases of sleep that a person goes through during a sleep cycle. Each stage is characterized by distinct physiological and neurological patterns. Understanding these stages can provide insights into sleep quality and overall health.

The different sleep stages are:

- **awake**: The state of being fully conscious and alert.
- **sleeping**: A general term for being in a state of sleep.
- **out_of_bed**: The state when a person is not in bed, possibly indicating a brief interruption in sleep.
- **light**: A stage of sleep where the body begins to relax, and the heart rate slows down. It is easier to wake up from this stage.
- **deep**: A restorative stage of sleep where the body repairs and regrows tissues, builds bone and muscle, and strengthens the immune system.
- **rem**: Rapid Eye Movement sleep, a stage where dreaming occurs, and the brain is very active. It plays a role in memory consolidation and mood regulation.
- **awake_in_bed**: The state of being awake while still in bed, often occurring before falling asleep or after waking up.
- **nap**: A short sleep, typically taken during the day, that can help improve alertness and performance.
- **unknown**: A stage that cannot be classified into any of the known categories, possibly due to insufficient data or anomalies in the sleep pattern.


### Sleep Attribution Date

The sleep date attribution follows two simple rules to determine which date a sleep record should be associated with:

1. **Provider Payload Date**: The primary source of truth is the date provided in the payload from the sleep tracking provider. This date is used if available.

2. **End Date Rule**: If the provider payload date is not available, the sleep date is attributed to the day on which the sleep session ended.

This straightforward approach ensures consistent date attribution for sleep records, regardless of when the sleep session started or ended.


### Main Sleep and Nap

There are two types of sleep: main sleep and nap. There can be only one main sleep per day, which is the longest sleep period. A nap is a shorter sleep taken during the day and will have a `sleep_duration_nap` value.


### Sleep Durations

Total sleep duration is the sum of the durations of light, deep, and REM sleep stages, while total time in bed also includes time spent awake.
```
total sleep = light + deep + rem
time in bed = total sleep + awake
```
Note that nap time is not included in the total sleep time for a day.
Sleep latency refers to the estimated time from when rest begins until the first occurrence of light or deep sleep. The accuracy of sleep stages and latency depends entirely on the provider’s sensors and calculations.
Sleep duration values are reported in milliseconds.

List Sleeps

Get Sleep

Statistics are calculated based on the data available for a specific time period. The data is aggregated according to the time interval specified in your request. This means that if you request data with an hourly interval, the statistics will be aggregated and presented for each hour within the specified time range.

The aggregation process involves summing up or averaging the data points within each interval, depending on the type of statistic being queried. This allows you to see trends and patterns over time, making it easier to analyze the data and draw meaningful insights. 

<Note>
Refer to the different statistics types in the [Statistics Types](/api-docs/statistics_matrix) section for more information on how the data is aggregated for each type.
</Note>

#### Coordinated Universal Time

The `/statistics` endpoint uses Coordinated Universal Time (UTC) for all its calculations. This standardization ensures that data is consistent and comparable across different time zones. By using UTC, the API provides a global view of the data, which is crucial for applications that require a uniform time reference. This approach contrasts with the `/statistics/daily` endpoint, which uses the user's local timezone for calculations, offering a more personalized view.



Statistics

Daily Statistics are calculated based on the data available for a specific time period. The data is aggregated for each day based on the user's local timezone.
The aggregation process involves summing up or averaging the data points within each interval, depending on the type of statistic being queried. This allows you to see trends and patterns over time, making it easier to analyze the data and draw meaningful insights. 

<Note>
Refer to the different statistics types in the [Statistics Types](/api-docs/statistics_matrix) section for more information on how the data is aggregated for each type.
</Note>

#### User's Local Timezone

The `/statistics/daily` endpoint uses the user's local timezone for all its calculations. This approach ensures that the data reflects the user's actual daily activity patterns, providing a more personalized view. By using the local timezone, the API tailors the data to the user's specific context, which is particularly useful for applications that focus on individual user experiences. This approach contrasts with the `/statistics` endpoint, which uses Coordinated Universal Time (UTC) for calculations, offering a standardized global view.


Daily Statistics

List Workouts

Get a single workout for a user by its activity ID

Get Workout

This document provides a comprehensive overview of all providers, detailing their capabilities. The list below summarizes the key features supported by each provider.

Supported Providers

This document provides a comprehensive overview of all metrics, detailing their providers, units, and descriptions. The table below summarizes the key features supported by each metric.

Metric Types and Units

This document provides a comprehensive overview of all activities, detailing their tags and descriptions. The table below summarizes the key features supported by each activity.

Activity Types and Tags

This document provides a comprehensive overview of all statistics, detailing their methods, metrics, units, and descriptions. The table below summarizes the key features supported by each statistic.

Statistic Types and Methods

Release Notes

This document provides a comprehensive overview of the Spike SDK for iOS, detailing its features and capabilities.

Setup Guide

Usage Guide

Background delivery ensures that data updates are sent to your backend via webhooks, even when the application is in the background or closed.

Background Delivery

Logs and Debugging

This document provides a comprehensive overview of the Spike SDK for android, detailing its features and capabilities.

This document provides a comprehensive overview of the Spike SDK for React Native, detailing its features and capabilities.

This document provides a comprehensive overview of the Spike SDK for Flutter, detailing its features and capabilities.

Integrating with SpikeAPI

API Reference: User Management

API Reference: Querying Data

Types and Definitions

Release Notes

Querying Data

Query Options Overview

Choosing the Right Query Option

Integrating with SpikeAPI

API Reference: User Management

API Reference: Querying Data

Types and Definitions

Release Notes

​Query Options Overview

​Choosing the Right Query Option

Query Options Overview

Choosing the Right Query Option