Skip to content

Activities

Data Model

For more information about data models related to activity data, please refer to the Data Model documentation.

Activity metadata

Activity metadata contains data such as an id, sport type, start and end times, etc. of activities.

Retrieving metadata for activities is done by using the get_activities method.

import sweatstack as ss


activities = ss.get_activities()

By default, this will return a list of the last 100 activities. Check the reference for more options for filtering the returned activities.

Alternatively, to receive the activities as a pandas DataFrame, you can use the as_dataframe keyword argument.

activities = ss.get_activities(as_dataframe=True)

Datetime operations

The start and end columns of the returned DataFrame are timezone aware. Because these columns can contain datetime objects with different time zones and because pandas datatime64[ns] columns only support one timezone, the dtype of these columns is object. For your convenience, start_local and end_local columns are also included in the returned DataFrame, containing the localized start and end times.

A common usecase for the returned pandas DataFrame is to apply some rolling operation on the activity start times, for example a 7-day rolling sum of the activity distances. This is a typical usecase for the start_local column, which contains the localized start times.

activities.rolling("7d", on="start_local")["summary.distance"].sum()

Activity data

Activity data is the timeseries data of an activity.

To get the activity data for an activity, you can use the get_activity_data method:

data = ss.get_activity_data(activity_id)

The returned dataframe is a pandas DataFrame with the activity data.

Longitudinal data

Longitudinal data is activity data from multiple activities.

To get longitudinal data, you can use the get_longitudinal_data method:

data = ss.get_longitudinal_data(
    sports=["running"],
    start=start_date,
)

The returned dataframe is a pandas DataFrame with a timezone-aware datetime index.

Uploading files

SweatStack allows uploading activity files. At the moment only .fit files are supported (contact me if you need other formats).

Required scopes

Uploading files requires an API key with scope data:write, ensure you request this scope during user authorization. More info here.

Details:

  • Method: POST
  • Content-Type: multipart/form-data
  • File limitation: Up to 10 files can be uploaded simultaneously
  • Supported format: Currently only .fit files are supported

Responses:

  • Success: 202 Accepted
  • Validation error: 422 Unprocessable Entity

Example request:

curl -X POST "https://api.sweatstack.com/api/v1/activities/upload" \
    -H "Authorization: Bearer {your_api_key}" \
    -F "[email protected]" \
    -F "[email protected]"

After the request is accepted, the activities will be processed in the background and the processed data will be available in the Activity data endpoint. Processing of uploaded files typically takes a few seconds.

Warning

This is not yet implemented in the Python client.