stravalib.client.Client

class stravalib.client.Client(access_token: str | None = None, rate_limit_requests: bool = True, rate_limiter: RateLimiter | None = None, requests_session: Session | None = None, token_expires: int | None = None, refresh_token: str | None = None)

Main client class for interacting with the exposed Strava v3 API methods.

This class can be instantiated without an access_token when performing authentication; however, most methods will require a valid access token.

__init__(access_token: str | None = None, rate_limit_requests: bool = True, rate_limiter: RateLimiter | None = None, requests_session: Session | None = None, token_expires: int | None = None, refresh_token: str | None = None) → None

Initialize a new client object.

Parameters:

• access_token (str) – The token that provides access to a specific Strava account. If empty, assume that this account is not yet authenticated.

• rate_limit_requests (bool) – Whether to apply a rate limiter to the requests. (default True)

• rate_limiter (callable) – A stravalib.util.limiter.RateLimiter object to use. If not specified (and rate_limit_requests is True), then stravalib.util.limiter.DefaultRateLimiter will be used.

• requests_session (requests.Session() object) – (Optional) pass request session object.

• token_expires (int) – epoch timestamp – seconds since jan 1 1970 (Epoch timestamp) This represents the date and time that the token will expire. It is used to automatically check and refresh the token in the client method on all API requests.

• refresh_token (str)

Methods

_get_streams(stream_url[, types, ...])	Generic method to retrieve stream data for activity, effort or segment.
_utc_datetime_to_epoch(activity_datetime)	Convert the specified datetime value to a unix epoch timestamp (seconds since epoch).
_validate_activity_type(params, ...)	Validate activity type and sport type values.
authorization_url(client_id, redirect_uri[, ...])	Get the URL needed to authorize your application to access a Strava user's information.
create_activity(name, start_date_local, ...)	Create a new manual activity.
create_subscription(client_id, ...[, ...])	Creates a webhook event subscription.
deauthorize()	Deauthorize the application.
delete_subscription(subscription_id, ...)	Unsubscribe from webhook events for an existing subscription.
exchange_code_for_token(client_id, ...[, ...])	Exchange the temporary authorization code (returned with redirect from Strava authorization URL) for a short-lived access token and a refresh token (used to obtain the next access token later on).
explore_segments(bounds[, activity_type, ...])	Returns an array of up to 10 segments.
get_activities([before, after, limit])	Get activities for authenticated user sorted by newest first.
get_activity(activity_id[, include_all_efforts])	Gets specified activity.
get_activity_comments(activity_id[, ...])	Gets the comments for an activity.
get_activity_kudos(activity_id[, limit])	Gets the kudos for an activity.
get_activity_laps(activity_id)	Gets the laps from an activity.
get_activity_photos(activity_id[, size, ...])	Gets the photos from an activity.
get_activity_streams(activity_id[, types, ...])	Returns a stream for an activity.
get_activity_zones(activity_id)	Gets activity zones for activity.
get_athlete()	Gets the specified athlete; if athlete_id is None then retrieves a detail-level representation of currently authenticated athlete; otherwise summary-level representation returned of athlete.
get_athlete_clubs([limit])	List the clubs for the currently authenticated athlete.
get_athlete_koms(athlete_id[, limit])	Gets Q/KOMs/CRs for specified athlete.
get_athlete_starred_segments(athlete_id[, limit])	Returns a summary representation of the segments starred by the
get_athlete_stats([athlete_id])	Returns Statistics for the athlete.
get_athlete_zones()	Get the authenticated athlete's heart rate and power zones
get_club(club_id)	Return a specific club object.
get_club_activities(club_id[, limit])	Gets the activities associated with specified club.
get_club_admins(club_id[, limit])	Returns a list of the administrators of a given club.
get_club_members(club_id[, limit])	Gets the member objects for specified club ID.
get_effort_streams(effort_id[, types, ...])	Returns an streams for an effort.
get_gear(gear_id)	Get details for an item of gear.
get_route(route_id)	Gets specified route.
get_route_streams(route_id)	Returns streams for a route.
get_routes([athlete_id, limit])	Gets the routes list for an authenticated user.
get_segment(segment_id)	Gets a specific segment by ID.
get_segment_effort(effort_id)	Return a specific segment effort by ID.
get_segment_efforts(segment_id[, ...])	Gets all efforts on a particular segment sorted by start_date_local
get_segment_streams(segment_id[, types, ...])	Returns streams for a segment.
get_starred_segments([limit])	Returns a summary representation of the segments starred by the
handle_subscription_callback(raw[, verify_token])	Validate callback request and return valid response with challenge.
handle_subscription_update(raw)	Converts a raw subscription update into a model.
join_club(club_id)	Joins the club on behalf of authenticated athlete.
leave_club(club_id)	Leave club on behalf of authenticated user.
list_subscriptions(client_id, client_secret)	List current webhook event subscriptions in place for the current application.
refresh_access_token(client_id, ...)	Exchanges the previous refresh token for a short-lived access token and a new refresh token (used to obtain the next access token later on).
update_activity(activity_id[, name, ...])	Updates the properties of a specific activity.
update_athlete([city, state, country, sex, ...])	Updates the properties of the authorized athlete.
upload_activity(activity_file, data_type[, ...])	Uploads a GPS file (tcx, gpx) to create a new activity for current athlete.

Attributes

access_token	The currently configured authorization token.
refresh_token	The currently configured authorization token.
token_expires	The currently configured authorization token.

property access_token: str | None

The currently configured authorization token.

authorization_url(client_id: int, redirect_uri: str, approval_prompt: Literal['auto', 'force'] = 'auto', scope: list[Literal['read', 'read_all', 'profile:read_all', 'profile:write', 'activity:read', 'activity:read_all', 'activity:write']] | Literal['read', 'read_all', 'profile:read_all', 'profile:write', 'activity:read', 'activity:read_all', 'activity:write'] | None = None, state: str | None = None) → str

Get the URL needed to authorize your application to access a Strava user’s information.

See https://developers.strava.com/docs/authentication/

Parameters:

• client_id (int) – The numeric developer client id.

• redirect_uri (str) – The URL that Strava will redirect to after successful (or failed) authorization.

• approval_prompt (str, default='auto') – Whether to prompt for approval even if approval already granted to app. Choices are ‘auto’ or ‘force’.

• scope (list[str], default = None) – The access scope required. Omit to imply “read” and “activity:read” Valid values are ‘read’, ‘read_all’, ‘profile:read_all’, ‘profile:write’, ‘activity:read’, ‘activity:read_all’, ‘activity:write’.

• state (str, default=None) – An arbitrary variable that will be returned to your application in the redirect URI.

Returns:

A string containing the url required to authorize with the Strava API.

Return type:

str

create_activity(name: str, start_date_local: datetime | str, elapsed_time: int | timedelta, sport_type: str | None = None, activity_type: str | None = None, description: str | None = None, distance: Quantity[float] | float | None = None, trainer: bool | None = None, commute: bool | None = None) → DetailedActivity

Create a new manual activity.

If you would like to create an activity from an uploaded GPS file, see the stravalib.client.Client.upload_activity() method instead.

Parameters:

• name (str) – The name of the activity.

• activity_type (str, default=None) – The activity type (case-insensitive). Deprecated. Prefer to use sport_type. In a request where both type and sport_type are present, this field will be ignored. See https://developers.strava.com/docs/reference/#api-models-UpdatableActivity. For possible values see: stravalib.model.DetailedActivity.TYPES

• sport_type (str, default=None) – For possible values (case-sensitive) see: For possible values see: stravalib.model.DetailedActivity.SPORT_TYPES

• start_date_local (class:datetime.datetime or string in ISO8601 format) – Local date/time of activity start. (TZ info will be ignored)

• elapsed_time (class:datetime.timedelta or int (seconds)) – The time in seconds or a datetime.timedelta object.

• description (str, default=None) – The description for the activity.

• distance (pint.Quantity or float (meters), default=None) – The distance in meters (float) or a pint.Quantity instance.

• trainer (bool) – Whether this activity was completed using a trainer (or not)

• commute (bool) – Whether the activity is a commute or not.

Notes

See: https://developers.strava.com/docs/reference/#api-Uploads-createUpload See: https://developers.strava.com/docs/reference/#api-Activities-createActivity

create_subscription(client_id: int, client_secret: str, callback_url: str, verify_token: str = 'STRAVA') → Subscription

Creates a webhook event subscription.

Parameters:

• client_id (int) – application’s ID, obtained during registration

• client_secret (str) – application’s secret, obtained during registration

• callback_url (str) – callback URL where Strava will first send a GET request to validate, then subsequently send POST requests with updates

• verify_token (str) – a token you can use to verify Strava’s GET callback request (Default value = model.Subscription.VERIFY_TOKEN_DEFAULT)

Returns:

class

Return type:

stravalib.model.Subscription

Notes

verify_token is set to a default in the event that the author doesn’t want to specify one.

The application must have permission to make use of the webhook API. Access can be requested by contacting developers -at- strava.com. An instance of stravalib.model.Subscription.

deauthorize() → None

Deauthorize the application. This causes the application to be removed from the athlete’s “My Apps” settings page.

https://developers.strava.com/docs/authentication/#deauthorization

delete_subscription(subscription_id: int, client_id: int, client_secret: str) → None

Unsubscribe from webhook events for an existing subscription.

Parameters:

• subscription_id (int) – ID of subscription to remove.

• client_id (int) – application’s ID, obtained during registration

• client_secret (str) – application’s secret, obtained during registration

Return type:

Deletes the specific subscription using the subscription ID

exchange_code_for_token(client_id: int, client_secret: str, code: str, return_athlete: bool = False) → AccessInfo | tuple[AccessInfo, SummaryAthlete | None]

Exchange the temporary authorization code (returned with redirect from Strava authorization URL) for a short-lived access token and a refresh token (used to obtain the next access token later on).

Parameters:

• client_id (int) – The numeric developer client id.

• client_secret (str) – The developer client secret

• code (str) – The temporary authorization code

• return_athlete (bool (default = False)) – Whether to return a SummaryAthlete object (or not) This parameter is currently undocumented and could change at any time.

Returns:

• AccessInfo – TypedDictionary containing the access_token, refresh_token and expires_at (number of seconds since Epoch when the provided access token will expire)

• tuple –

  Contains:

  • the AccessInfo typed dict containing token values

  • a SummaryAthlete object representing the authenticated user.

Notes

Strava by default returns SummaryAthlete information during this exchange. However this return is currently undocumented and could change at any time.

explore_segments(bounds: tuple[float, float, float, float] | tuple[tuple[float, float], tuple[float, float]], activity_type: str | None = None, min_cat: int | None = None, max_cat: int | None = None) → list[SegmentExplorerResult]

Returns an array of up to 10 segments.

https://developers.strava.com/docs/reference/#api-Segments-exploreSegments

Parameters:

• bounds (tuple of 4 floats or tuple of 2 (lat,lon) tuples) – list of bounding box corners lat/lon [sw.lat, sw.lng, ne.lat, ne.lng] (south,west,north,east)

• activity_type (str) – optional, default is riding) ‘running’ or ‘riding’

• min_cat (int, optional, default=None) – Minimum climb category filter

• max_cat (int, optional, default=None) – Maximum climb category filter

Returns:

An list of stravalib.model.Segment.

Return type:

list

get_activities(before: datetime | str | None = None, after: datetime | str | None = None, limit: int | None = None) → BatchedResultsIterator[SummaryActivity]

Get activities for authenticated user sorted by newest first.

https://developers.strava.com/docs/reference/#api-Activities-getLoggedInAthleteActivities

Parameters:

• before (datetime.datetime or str or None, default=None) – Result will start with activities whose start date is before specified date. (UTC)

• after (datetime.datetime or str or None, default=None) – Result will start with activities whose start date is after specified value. (UTC)

• limit (int or None, default=None) – Maximum number of activities to return.

Returns:

An iterator of stravalib.model.SummaryActivity objects.

Return type:

stravalib.model.BatchedResultsIterator

get_activity(activity_id: int, include_all_efforts: bool = False) → DetailedActivity

Gets specified activity.

Will be detail-level activity return if owned by authenticated user; otherwise it will be summary-level.

Parameters:

• activity_id (int) – The ID of activity to fetch.

• include_all_efforts (bool, default=False) – Whether to include segment efforts - only available to the owner of the activity.

Returns:

A DetailedActivity object containing the requested activity data.

Return type:

model.DetailedActivity

Notes

https://developers.strava.com/docs/reference/#api-Activities-getActivityById

get_activity_comments(activity_id: int, markdown: bool = False, limit: int | None = None) → BatchedResultsIterator[Comment]

Gets the comments for an activity.

https://developers.strava.com/docs/reference/#api-Activities-getCommentsByActivityId

Parameters:

• activity_id (int) – The activity for which to fetch comments.

• markdown (bool) – Whether to include markdown in comments (default is false/filterout)

• limit (int) – Max rows to return (default unlimited).

Returns:

class – An iterator of stravalib.strava_model.Comment objects.

Return type:

BatchedResultsIterator

get_activity_kudos(activity_id: int, limit: int | None = None) → BatchedResultsIterator[SummaryAthlete]

Gets the kudos for an activity.

https://developers.strava.com/docs/reference/#api-Activities-getKudoersByActivityId

Parameters:

• activity_id (int) – The activity for which to fetch kudos.

• limit (int) – Max rows to return (default unlimited).

Returns:

class – An iterator of stravalib.model.ActivityKudos objects.

Return type:

BatchedResultsIterator

get_activity_laps(activity_id: int) → BatchedResultsIterator[Lap]

Gets the laps from an activity.

https://developers.strava.com/docs/reference/#api-Activities-getLapsByActivityId

Parameters:

activity_id (int) – The activity for which to fetch laps.

Returns:

class – An iterator of stravalib.model.Lap objects.

Return type:

BatchedResultsIterator

get_activity_photos(activity_id: int, size: int | None = None, only_instagram: bool = False) → BatchedResultsIterator[ActivityPhoto]

Gets the photos from an activity.

https://developers.strava.com/docs/reference/#api-Activities

Parameters:

• activity_id (int) – The activity for which to fetch photos.

• size (int, default=None) – the requested size of the activity’s photos. URLs for the photos will be returned that best match the requested size. If not included, the smallest size is returned

• only_instagram (bool, default=False) – Parameter to preserve legacy behavior of only returning Instagram photos.

Returns:

class – An iterator of stravalib.model.ActivityPhoto objects.

Return type:

BatchedResultsIterator

get_activity_streams(activity_id: int, types: list[str] | None = None, resolution: Literal['low', 'medium', 'high'] | None = None, series_type: Literal['time', 'distance'] | None = None) → dict[str, Stream]

Returns a stream for an activity.

https://developers.strava.com/docs/reference/#api-Streams-getActivityStreams

Streams represent the raw spatial data for the uploaded file. External applications may only access this information for activities owned by the authenticated athlete.

Streams are available in 11 different types. If the stream is not available for a particular activity it will be left out of the request results.

Streams types are: time, latlng, distance, altitude, velocity_smooth,

heartrate, cadence, watts, temp, moving, grade_smooth

Parameters:

• activity_id (int) – The ID of activity.

• types (list[str], optional, default=None) – A list of the types of streams to fetch.

• resolution (str, optional) –

  Indicates desired number of data points. ‘low’ (100), ‘medium’ (1000) or ‘high’ (10000). .. deprecated:

  This param is not officially supported by the Strava API and
  may be removed in the future.
  

• series_type (str, optional) –

  Relevant only if using resolution either ‘time’ or ‘distance’. Used to index the streams if the stream is being reduced. .. deprecated:

  This param is not officially supported by the Strava API and may be
  removed in the future.
  

Returns:

A dictionary of stravalib.model.Stream from the activity

Return type:

dict

get_activity_zones(activity_id: int) → list[ActivityZone]

Gets activity zones for activity.

Activity zones relate to a users effort (heartrate and power).

https://developers.strava.com/docs/reference/#api-Activities-getZonesByActivityId

Parameters:

activity_id (int) – The activity for which to get zones.

Returns:

A list of stravalib.model.ActivityZone objects.

Return type:

list

Notes

Activity zones require a Strava premium account. The Strava API has the return value for activity zones incorrectly typed as int when it can return either int or float.

get_athlete() → DetailedAthlete

Gets the specified athlete; if athlete_id is None then retrieves a detail-level representation of currently authenticated athlete; otherwise summary-level representation returned of athlete.

Returns:

class – The stravalib.model.DetailedAthlete model object.

Return type:

stravalib.model.DetailedAthlete

Notes

See: https://developers.strava.com/docs/reference/#api-Athletes

https://developers.strava.com/docs/reference/#api-Athletes-getLoggedInAthlete

get_athlete_clubs(limit: int | None = None) → BatchedResultsIterator[SummaryClub]

List the clubs for the currently authenticated athlete.

https://developers.strava.com/docs/reference/#api-Clubs-getLoggedInAthleteClubs

limitint or None, default=None

Maximum number of club objects to return.

Returns:

An iterator of stravalib.model.SummaryClub objects

Return type:

stravalib.model.BatchedResultsIterator

get_athlete_koms(athlete_id: int, limit: int | None = None) → BatchedResultsIterator[SegmentEffort]

Gets Q/KOMs/CRs for specified athlete.

KOMs are returned as stravalib.model.SegmentEffort objects.

Parameters:

• athlete_id (int) – The ID of the athlete.

• limit (int) – Maximum number of KOM segment efforts to return (default unlimited).

Returns:

class – An iterator of stravalib.model.SegmentEffort objects.

Return type:

BatchedResultsIterator

get_athlete_starred_segments(athlete_id: int, limit: int | None = None) → BatchedResultsIterator[Segment]

Returns a summary representation of the segments starred by the

specified athlete. Pagination is supported.

https://developers.strava.com/docs/reference/#api-Segments-getLoggedInAthleteStarredSegments

Parameters:

• athlete_id (int) – The ID of the athlete.

• limit (int, optional, default=None) – Limit number of starred segments returned.

Returns:

class – An iterator of stravalib.model.Segment starred by authenticated user.

Return type:

BatchedResultsIterator

get_athlete_stats(athlete_id: int | None = None) → AthleteStats

Returns Statistics for the athlete. athlete_id must be the id of the authenticated athlete or left blank. If it is left blank two requests will be made - first to get the authenticated athlete’s id and second to get the Stats.

https://developers.strava.com/docs/reference/#api-Athletes-getStats

Parameters:

athlete_id (int, default=None) – Strava ID value for the athlete.

Returns:

A model containing the Stats

Return type:

stravalib.model.AthleteStats

Notes

Note that this will return the stats for public activities only, regardless of the scopes of the current access token.

get_athlete_zones() → Zones

Get the authenticated athlete’s heart rate and power zones

Returns:

class – The athlete zones model object.

Return type:

stravalib.model.Zones

get_club(club_id: int) → DetailedClub

Return a specific club object.

https://developers.strava.com/docs/reference/#api-Clubs-getClubById

Parameters:

club_id (int) – The ID of the club to fetch.

Returns:

class

Return type:

model.DetailedClub object containing the club data.

Notes

https://developers.strava.com/docs/reference/#api-Clubs-getClubById

get_club_activities(club_id: int, limit: int | None = None) → BatchedResultsIterator[ClubActivity]

Gets the activities associated with specified club.

https://developers.strava.com/docs/reference/#api-Clubs-getClubActivitiesById

Parameters:

• club_id (int) – The numeric ID for the club.

• limit (int) – Maximum number of activities to return. (default unlimited)

Returns:

class – An iterator of stravalib.model.ClubActivity objects.

Return type:

BatchedResultsIterator

get_club_admins(club_id: int, limit: int | None = None) → BatchedResultsIterator[SummaryAthlete]

Returns a list of the administrators of a given club.

https://developers.strava.com/docs/reference/#api-Clubs-getClubAdminsById

Parameters:

• club_id (int) – The numeric ID for the club.

• limit (int) – Maximum number of admins to return. (default unlimited)

Returns:

class – An iterator of stravalib.model.SummaryAthlete objects.

Return type:

BatchedResultsIterator

get_club_members(club_id: int, limit: int | None = None) → BatchedResultsIterator[ClubAthlete]

Gets the member objects for specified club ID.

https://developers.strava.com/docs/reference/#api-Clubs-getClubMembersById

Parameters:

• club_id (int) – The numeric ID for the club.

• limit (int) – Maximum number of athletes to return. (default unlimited)

Returns:

class – An iterator of stravalib.model.Athlete objects.

Return type:

BatchedResultsIterator

get_effort_streams(effort_id: int, types: list[str] | None = None, resolution: Literal['low', 'medium', 'high'] | None = None, series_type: Literal['time', 'distance'] | None = None) → dict[str, Stream]

Returns an streams for an effort.

https://developers.strava.com/docs/reference/#api-Streams-getSegmentEffortStreams

Streams represent the raw data of the uploaded file. External applications may only access this information for activities owned by the authenticated athlete.

Streams are available in 11 different types. If the stream is not available for a particular activity it will be left out of the request results.

Streams types are: time, latlng, distance, altitude, velocity_smooth,

heartrate, cadence, watts, temp, moving, grade_smooth

Parameters:

• effort_id (int) – The ID of effort.

• types (list, optional, default=None) – A list of the the types of streams to fetch.

• resolution (str, optional) –

  Indicates desired number of data points. ‘low’ (100), ‘medium’ (1000) or ‘high’ (10000). .. deprecated:

  This param is not officially supported by the Strava API and
  may be removed in the future.
  

• series_type (str, optional) –

  Relevant only if using resolution either ‘time’ or ‘distance’. Used to index the streams if the stream is being reduced. .. deprecated:

  This param is not officially supported by the Strava API and
  may be removed in the future.
  

Returns:

An dictionary of stravalib.model.Stream from the effort.

Return type:

dict

get_gear(gear_id: str) → DetailedGear

Get details for an item of gear.

https://developers.strava.com/docs/reference/#api-Gears

Parameters:

gear_id (str) – The gear id.

Returns:

class

Return type:

stravalib.strava_model.DetailedGear

get_route(route_id: int) → Route

Gets specified route.

Will be detail-level if owned by authenticated user; otherwise summary-level.

https://developers.strava.com/docs/reference/#api-Routes-getRouteById

Parameters:

route_id (int) – The ID of route to fetch.

Returns:

class – A model.Route object containing the route data.

Return type:

model.Route

get_route_streams(route_id: int) → dict[str, Stream]

Returns streams for a route.

Streams represent the raw data of the saved route. External applications may access this information for all public routes and for the private routes of the authenticated athlete. The 3 available route stream types distance, altitude and latlng are always returned.

See: https://developers.strava.com/docs/reference/#api-Streams-getRouteStreams

Parameters:

route_id (int) – The ID of activity.

Returns:

A dictionary of stravalib.model.Stream from the route.

Return type:

dict

get_routes(athlete_id: int | None = None, limit: int | None = None) → BatchedResultsIterator[Route]

Gets the routes list for an authenticated user.

https://developers.strava.com/docs/reference/#api-Routes-getRoutesByAthleteId

Parameters:

• athlete_id (int, default=None) – Strava athlete ID

• limit (int, default=unlimited) – Max rows to return.

Returns:

class – An iterator of stravalib.model.Route objects.

Return type:

BatchedResultsIterator

get_segment(segment_id: int) → Segment

Gets a specific segment by ID.

https://developers.strava.com/docs/reference/#api-SegmentEfforts-getSegmentEffortById

Parameters:

segment_id (int) – The segment to fetch.

Returns:

class – A segment object.

Return type:

stravalib.model.Segment

get_segment_effort(effort_id: int) → SegmentEffort

Return a specific segment effort by ID.

Parameters:

effort_id (int) – The id of associated effort to fetch.

Returns:

class – The specified effort on a segment.

Return type:

stravalib.model.SegmentEffort

Notes

https://developers.strava.com/docs/reference/#api-SegmentEfforts

get_segment_efforts(segment_id: int, athlete_id: int | None = None, start_date_local: datetime | str | None = None, end_date_local: datetime | str | None = None, limit: int | None = None) → BatchedResultsIterator[BaseEffort]

Gets all efforts on a particular segment sorted by start_date_local

Returns an array of segment effort summary representations sorted by start_date_local ascending or by elapsed_time if an athlete_id is provided.

NOTES: * The athlete_id sorting only works if you do NOT provide start and end dates. * If no date filtering parameters are provided, all efforts for the segment will be returned.

Date range filtering is accomplished using an inclusive start and end time. start_date_local and end_date_local must be sent together. For open ended ranges pick dates significantly in the past or future. The filtering is done over local time for the segment, so there is no need for timezone conversion. For example, all efforts on Jan. 1st, 2024 for a segment in San Francisco, CA can be fetched using 2024-01-01T00:00:00Z and 2024-01-01T23:59:59Z.

This endpoint requires a Strava subscription.

Parameters:

• segment_id (int) – ID for the segment of interest

• start_date_local (datetime.datetime or str, optional, default=None) – Efforts before this date will be excluded. Either as ISO8601 or datetime object

• end_date_local (datetime.datetime or str, optional, default=None) – Efforts after this date will be excluded. Either as ISO8601 or datetime object

• limit (int, default=None, optional) –

  limit number of efforts. This parameter has been removed by Strava and will be removed in stravalib in the near future. .. deprecated:

  This param is not supported by the Strava API and may be
  removed in the future.
  

• athlete_id (int, default=None) –

  Strava ID for the athlete. Used to sort efforts by duration. Can only be used if start and end date are not provided. .. deprecated:

  This param is not supported by the Strava API and may be
  removed in the future.
  

Returns:

class – An iterator of stravalib.model.SegmentEffort efforts on a segment.

Return type:

BatchedResultsIterator

Notes

https://developers.strava.com/docs/reference/#api-SegmentEfforts-getEffortsBySegmentId

get_segment_streams(segment_id: int, types: list[str] | None = None, resolution: Literal['low', 'medium', 'high'] | None = None, series_type: Literal['time', 'distance'] | None = None) → dict[str, Stream]

Returns streams for a segment.

https://developers.strava.com/docs/reference/#api-Streams-getSegmentStreams

Streams represent the raw data of the uploaded file. External applications may only access this information for activities owned by the authenticated athlete.

Streams are available in 11 different types. If the stream is not available for a particular activity it will be left out of the request results.

Streams types are: time, latlng, distance, altitude, velocity_smooth, heartrate, cadence, watts, temp, moving, grade_smooth

Parameters:

• segment_id (int) – The ID of segment.

• types (list, optional, default=None) – A list of the the types of streams to fetch.

• resolution (str, optional) –

  Indicates desired number of data points. ‘low’ (100), ‘medium’ (1000) or ‘high’ (10000). .. deprecated:

  This param is not officially supported by the Strava API and may be
  removed in the future.
  

• series_type (str, optional) –

  Relevant only if using resolution either ‘time’ or ‘distance’. Used to index the streams if the stream is being reduced. .. deprecated:

  This param is not officially supported by the Strava API and may be
  removed in the future.
  

Returns:

An dictionary of stravalib.model.Stream from the effort.

Return type:

dict

get_starred_segments(limit: int | None = None) → BatchedResultsIterator[SummarySegment]

Returns a summary representation of the segments starred by the

authenticated user. Pagination is supported.

https://developers.strava.com/docs/reference/#api-Segments-getLoggedInAthleteStarredSegments

Parameters:

limit (int, optional, default=None) – Limit number of starred segments returned.

Returns:

class – An iterator of stravalib.model.SummarySegment starred by authenticated user.

Return type:

BatchedResultsIterator

handle_subscription_callback(raw: dict[str, Any], verify_token: str = 'STRAVA') → dict[str, str]

Validate callback request and return valid response with challenge.

Parameters:

• raw (dict) – The raw JSON response which will be serialized to a Python dict.

• verify_token (default=model.Subscription.VERIFY_TOKEN_DEFAULT)

Returns:

The JSON response expected by Strava to the challenge request.

Return type:

dict[str, str]

handle_subscription_update(raw: dict[str, Any]) → SubscriptionUpdate

Converts a raw subscription update into a model.

Parameters:

raw (dict) – The raw json response deserialized into a dict.

Returns:

class – The subscription update model object.

Return type:

stravalib.model.SubscriptionUpdate

join_club(club_id: int) → None

Joins the club on behalf of authenticated athlete.

(Access token with write permissions required.)

Parameters:

club_id (int) – The numeric ID of the club to join.

Returns:

• No actual return. This implements a post action that allows the athlete

• to join a club via an API.

leave_club(club_id: int) → None

Leave club on behalf of authenticated user.

(Access token with write permissions required.)

Parameters:

club_id (int)

Returns:

• No actual return. This implements a post action that allows the athlete

• to leave a club via an API.

list_subscriptions(client_id: int, client_secret: str) → BatchedResultsIterator[Subscription]

List current webhook event subscriptions in place for the current application.

Parameters:

• client_id (int) – application’s ID, obtained during registration

• client_secret (str) – application’s secret, obtained during registration

Returns:

class – An iterator of stravalib.model.Subscription objects.

Return type:

BatchedResultsIterator

refresh_access_token(client_id: int, client_secret: str, refresh_token: str) → AccessInfo

Exchanges the previous refresh token for a short-lived access token and a new refresh token (used to obtain the next access token later on).

Parameters:

• client_id (int) – The numeric developer client id.

• client_secret (str) – The developer client secret

• refresh_token (str) – The refresh token obtained from a previous authorization request

Returns:

Dictionary containing the access_token, refresh_token and expires_at (number of seconds since Epoch when the provided access token will expire)

Return type:

dict

property refresh_token: str | None

The currently configured authorization token.

property token_expires: int | None

The currently configured authorization token.

update_activity(activity_id: int, name: str | None = None, activity_type: str | None = None, sport_type: str | None = None, description: str | None = None, private: bool | None = None, commute: bool | None = None, trainer: bool | None = None, gear_id: str | None = None, device_name: str | None = None, hide_from_home: bool | None = None) → DetailedActivity

Updates the properties of a specific activity.

Parameters:

• activity_id (int) – The ID of the activity to update.

• name (str, default=None) – The name of the activity.

• activity_type (str, default=None) – The activity type (case-insensitive). Deprecated. Prefer to use sport_type. In a request where both type and sport_type are present, this field will be ignored. See https://developers.strava.com/docs/reference/#api-models-UpdatableActivity. For possible values see: stravalib.model.DetailedActivity.TYPES

• sport_type (str, default=None) – For possible values see: stravalib.model.DetailedActivity.SPORT_TYPES

• private (bool, default=None) – Whether the activity is private. .. deprecated:: 1.0 This param is not supported by the Strava API and may be removed in the future.

• commute (bool, default=None) – Whether the activity is a commute.

• trainer (bool, default=None) – Whether this is a trainer activity.

• gear_id (str, default=None) – Alphanumeric ID of gear (bike, shoes) used on this activity.

• description (str, default=None) – Description for the activity.

• device_name (str, default=None) – Device name for the activity .. deprecated:: 1.0 This param is not supported by the Strava API and may be removed in the future.

• hide_from_home (bool, default=None) – Whether the activity is muted (hidden from Home and Club feeds).

Return type:

Updates the activity in the selected Strava account

Notes

See: https://developers.strava.com/docs/reference/#api-Activities-updateActivityById

update_athlete(city: str | None = None, state: str | None = None, country: str | None = None, sex: str | None = None, weight: float | None = None) → DetailedAthlete

Updates the properties of the authorized athlete.

https://developers.strava.com/docs/reference/#api-Athletes-updateLoggedInAthlete

Parameters:

• city (str, default=None) – City the athlete lives in .. deprecated:: 1.0 This param is not supported by the Strava API and may be removed in the future.

• state (str, default=None) – State the athlete lives in .. deprecated:: 1.0 This param is not supported by the Strava API and may be removed in the future.

• country (str, default=None) – Country the athlete lives in .. deprecated:: 1.0 This param is not supported by the Strava API and may be removed in the future.

• sex (str, default=None) – Sex of the athlete .. deprecated:: 1.0 This param is not supported by the Strava API and may be removed in the future.

• weight (float, default=None) – Weight of the athlete in kg (float)

upload_activity(activity_file: SupportsRead[str | bytes], data_type: Literal['fit', 'fit.gz', 'tcx', 'tcx.gz', 'gpx', 'gpx.gz'], name: str | None = None, description: str | None = None, activity_type: ActivityType | None = None, private: bool | None = None, external_id: str | None = None, trainer: bool | None = None, commute: bool | None = None) → ActivityUploader

Uploads a GPS file (tcx, gpx) to create a new activity for current athlete.

https://developers.strava.com/docs/reference/#api-Uploads-createUpload

Parameters:

• activity_file (TextIOWrapper, str or bytes) – The file object to upload or file contents.

• data_type (str) – File format for upload. Possible values: fit, fit.gz, tcx, tcx.gz, gpx, gpx.gz

• name (str, optional, default=None) – If not provided, will be populated using start date and location, if available

• description (str, optional, default=None) – The description for the activity

• activity_type (str, optional) – Case-insensitive type of activity. possible values: ride, run, swim, workout, hike, walk, nordicski, alpineski, backcountryski, iceskate, inlineskate, kitesurf, rollerski, windsurf, workout, snowboard, snowshoe Type detected from file overrides, uses athlete’s default type if not specified WARNING - This param is supported (as of 2022-11-15), but not documented and may be removed in the future.

• private (bool, optional, default=None) –

  Set to True to mark the resulting activity as private, ‘view_private’ permissions will be necessary to view the activity.

  Deprecated since version 1.0: This param is not supported by the Strava API and may be removed in the future.

• external_id (str, optional, default=None) – An arbitrary unique identifier may be specified which will be included in status responses.

• trainer (bool, optional, default=None) – Whether the resulting activity should be marked as having been performed on a trainer.

• commute (bool, optional, default=None) – Whether the resulting activity should be tagged as a commute.