Client class¶
Bases: OAuth2Mixin, DelegationMixin
url
property
writable
¶
This determines which SweatStack URL to use, allowing the use of a non-default instance.
This is useful for example during local development.
Please note that changing the url probably requires changing the OAUTH2_CLIENT_ID as well.
create_trace(*, timestamp, lactate=None, rpe=None, notes=None, power=None, speed=None, heart_rate=None, tags=None)
¶
Creates a new trace with the specified parameters.
This method creates a new trace entry with the given timestamp and optional measurement values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timestamp
|
datetime
|
The date and time when the trace was recorded. |
required |
lactate
|
float | None
|
Optional blood lactate concentration in mmol/L. |
None
|
rpe
|
int | None
|
Optional rating of perceived exertion (typically on a scale of 1-10). |
None
|
notes
|
str | None
|
Optional text notes associated with this trace. |
None
|
power
|
int | None
|
Optional power measurement in watts. |
None
|
speed
|
float | None
|
Optional speed measurement in meters per second. |
None
|
heart_rate
|
int | None
|
Optional heart rate measurement in beats per minute. |
None
|
tags
|
list[str] | None
|
Optional list of tags to associate with this trace. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
TraceDetails |
TraceDetails
|
The created trace object with all details. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activities(*, start=None, end=None, sports=None, tags=None, limit=100, as_dataframe=False)
¶
Gets a list of activities based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter activities. |
None
|
end
|
date | None
|
Optional end date to filter activities. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter activities by. Can be Sport objects or string IDs. |
None
|
tags
|
list[str] | None
|
Optional list of tags to filter activities by. |
None
|
limit
|
int
|
Maximum number of activities to return. Defaults to 100. |
100
|
as_dataframe
|
bool
|
Whether to return results as a pandas DataFrame. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
Generator[ActivitySummary, None, None] | DataFrame
|
Either a generator yielding ActivitySummary objects or a pandas DataFrame containing |
Generator[ActivitySummary, None, None] | DataFrame
|
the activities data, depending on the value of as_dataframe. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity(activity_id)
¶
Gets details for a specific activity by ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity to retrieve. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
ActivityDetails |
ActivityDetails
|
The activity details object containing all information about the activity. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity_data(activity_id, adaptive_sampling_on=None)
¶
Gets the raw data for a specific activity.
This method retrieves the time-series data for a given activity, with optional adaptive sampling to reduce data points for visualization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity. |
required |
adaptive_sampling_on
|
Literal['power', 'speed'] | None
|
Optional parameter to apply adaptive sampling on either "power" or "speed" data. If None, no adaptive sampling is applied. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the activity's time-series data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_activity_mean_max(activity_id, metric, adaptive_sampling=False)
¶
Gets the mean-max data for a specific activity.
This method retrieves the mean-max curve data for a given activity, which represents the maximum average value of a metric (power or speed) for different time durations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
activity_id
|
str
|
The unique identifier of the activity. |
required |
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate mean-max values for, either "power" or "speed". |
required |
adaptive_sampling
|
bool
|
Whether to apply adaptive sampling to reduce data points for visualization. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the mean-max curve data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_latest_activity(*, start=None, end=None, sport=None, tag=None)
¶
Gets the most recent activity based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter activities. |
None
|
end
|
date | None
|
Optional end date to filter activities. |
None
|
sport
|
Sport | None
|
Optional sport to filter activities by. Can be a Sport object or string ID. |
None
|
tag
|
str | None
|
Optional tag to filter activities by. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
ActivityDetails |
ActivityDetails
|
The most recent activity matching the filters. |
Raises:
| Type | Description |
|---|---|
StopIteration
|
If no activities match the filters. |
HTTPStatusError
|
If the API request fails. |
get_latest_activity_data(sport=None, adaptive_sampling_on=None)
¶
Gets the data for the latest activity of a specific sport.
This method retrieves the time series data for the most recent activity of the specified sport. If no sport is specified, it returns data for the latest activity regardless of sport.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sport
|
Sport | str | None
|
Optional sport to filter by. Can be a Sport enum or string. |
None
|
adaptive_sampling_on
|
Literal['power', 'speed'] | None
|
Optional metric to apply adaptive sampling for visualization. Can be either "power" or "speed". Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the activity data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_latest_activity_mean_max(metric, sport=None, adaptive_sampling=False)
¶
Gets the mean-max curve for the latest activity of a specific sport.
This method retrieves the mean-max curve data for the most recent activity of the specified sport. If no sport is specified, it returns data for the latest activity regardless of sport.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate the mean-max curve for. Can be either "power" or "speed". |
required |
sport
|
Sport | str | None
|
Optional sport to filter by. Can be a Sport enum or string. |
None
|
adaptive_sampling
|
bool
|
Whether to apply adaptive sampling to the mean-max curve data. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the mean-max curve data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_longitudinal_data(*, sport=None, sports=None, start, end=None, metrics=None, adaptive_sampling_on=None)
¶
Gets longitudinal data for activities within a specified date range.
This method retrieves aggregated data for activities that match the specified criteria, including sport type and date range. The data is returned as a pandas DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sport
|
Sport | str | None
|
Optional single sport to filter by. Can be a Sport enum or string. Cannot be used together with 'sports'. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter by. Can be a list of Sport enums or strings. Cannot be used together with 'sport'. |
None
|
start
|
date | str
|
The start date for the data range. Can be a date object or string in ISO format. |
required |
end
|
date | str | None
|
Optional end date for the data range. Can be a date object or string in ISO format. |
None
|
metrics
|
list[Metric | str] | None
|
Optional list of metrics to include in the results. Can be a list of Metric enums or strings. |
None
|
adaptive_sampling_on
|
Literal[power, speed] | Literal['power', 'speed'] | None
|
Optional metric to apply adaptive sampling for visualization. Can be either "power" or "speed". Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the longitudinal activity data. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If both 'sport' and 'sports' parameters are provided. |
HTTPStatusError
|
If the API request fails. |
get_longitudinal_mean_max(*, sport, metric, date=None, window_days=None)
¶
Gets the mean-max curve for a specific sport and metric.
This method retrieves the mean-max curve data for a given sport and metric, optionally filtered by date and window size.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sport
|
Sport | str
|
The sport to get mean-max data for. Can be a Sport enum or string ID. |
required |
metric
|
Literal[power, speed] | Literal['power', 'speed']
|
The metric to calculate mean-max for. Must be either "power" or "speed". |
required |
date
|
date | str | None
|
Optional reference date for the mean-max calculation. If provided, the mean-max curve will be calculated up to this date. Can be a date object or string in ISO format. |
None
|
window_days
|
int | None
|
Optional number of days to include in the calculation window before the reference date. If None, all available data is used. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A pandas DataFrame containing the mean-max curve data. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_sports(only_root=False)
¶
Gets a list of available sports.
This method retrieves all sports available to the user, with an option to only return root sports (top-level sports without parents).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
only_root
|
bool
|
If True, only returns root sports without parents. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
list[Sport]
|
list[Sport]: A list of Sport objects representing the available sports. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_tags()
¶
Gets a list of all tags used by the user.
This method retrieves all tags that the user has created or used across their activities and traces.
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: A list of tag strings. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_traces(*, start=None, end=None, sports=None, tags=None, limit=100, as_dataframe=False)
¶
Gets a list of traces based on specified filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
date | None
|
Optional start date to filter traces. |
None
|
end
|
date | None
|
Optional end date to filter traces. |
None
|
sports
|
list[Sport | str] | None
|
Optional list of sports to filter traces by. Can be Sport objects or string IDs. |
None
|
tags
|
list[str] | None
|
Optional list of tags to filter traces by. |
None
|
limit
|
int
|
Maximum number of traces to return. Defaults to 100. |
100
|
as_dataframe
|
bool
|
Whether to return results as a pandas DataFrame. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
Generator[TraceDetails, None, None] | DataFrame
|
Either a generator yielding TraceDetails objects or a pandas DataFrame containing |
Generator[TraceDetails, None, None] | DataFrame
|
the traces data, depending on the value of as_dataframe. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |
get_users()
¶
Gets a list of all users accessible to the current user.
This method retrieves all users that the current user has access to view. For regular users, this typically returns only their own user information. For admin users, this may return information about multiple users.
Returns:
| Type | Description |
|---|---|
list[UserSummary]
|
list[UserSummary]: A list of UserSummary objects containing basic user information. |
Raises:
| Type | Description |
|---|---|
HTTPStatusError
|
If the API request fails. |