API

Main Interaction

This part of the documentation covers the primary API for interacting with Strava.

Client

Provides the main interface classes for the Strava version 3 REST API.

class stravalib.client.Client(access_token=None, rate_limit_requests=True, rate_limiter=None, requests_session=None)[source]

Bases: object

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.

access_token[source]

The currently configured authorization token.

authorization_url(client_id, redirect_uri, approval_prompt='auto', scope=None, state=None)[source]

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

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) – Whether to prompt for approval even if approval already granted to app. Choices are ‘auto’ or ‘force’. (Default is ‘auto’)
  • scope (str) – The access scope required. Omit to imply “public”. Valid values are ‘public’, ‘write’, ‘view_private’, ‘view_private,write’
  • state (str) – An arbitrary variable that will be returned to your application in the redirect URI.
Returns:

The URL to use for authorization link.

Return type:

str

exchange_code_for_token(client_id, client_secret, code)[source]

Exchange the temporary authorization code (returned with redirect from strava authorization URL) for a permanent access token.

Parameters:
  • client_id (int) – The numeric developer client id.
  • client_secret (str) – The developer client secret
  • code (str) – The temporary authorization code
Returns:

The access token.

Return type:

str

get_activities(before=None, after=None, limit=None)[source]

Get activities for authenticated user sorted by newest first.

http://strava.github.io/api/v3/activities/

Parameters:
  • before (datetime.datetime or str) – Result will start with activities whose start date is before specified date. (UTC)
  • after (datetime.datetime or str) – Result will start with activities whose start date is after specified value. (UTC)
  • limit (int) – How many maximum activities to return.
get_athlete(athlete_id=None)[source]

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.

http://strava.github.io/api/v3/athlete/#get-details

http://strava.github.io/api/v3/athlete/#get-another-details

Param:athlete_id: The numeric ID of the athlete to fetch.
Type:athlete_id: int
Returns:The athlete model object.
Return type:stravalib.model.Athlete
get_athlete_friends(athlete_id=None, limit=None)[source]

Gets friends for current (or specified) athlete.

http://strava.github.io/api/v3/follow/#friends

:param athlete_id :type athlete_id: int :param limit: Maximum number of athletes to return (default unlimited). :type limit: int :return: An iterator of stravalib.model.Athlete objects. :rtype: BatchedResultsIterator

get_athlete_followers(athlete_id=None, limit=None)[source]

Gets followers for current (or specified) athlete.

http://strava.github.io/api/v3/follow/#followers

:param athlete_id :type athlete_id: int :param limit: Maximum number of athletes to return (default unlimited). :type limit: int :return: An iterator of stravalib.model.Athlete objects. :rtype: BatchedResultsIterator

get_both_following(athlete_id, limit=None)[source]
Retrieve the athletes who both the authenticated user and the indicated
athlete are following.

http://strava.github.io/api/v3/follow/#both

Parameters:
  • athlete_id (int) – The ID of the other athlete (for follower intersection with current athlete)
  • limit (int) – Maximum number of athletes to return. (default unlimited)
Returns:

An iterator of stravalib.model.Athlete objects.

Return type:

BatchedResultsIterator

get_athlete_clubs()[source]

List the clubs for the currently authenticated athlete.

http://strava.github.io/api/v3/clubs/#get-athletes

Return type:list of stravalib.model.Club
get_club(club_id)[source]

Return a specific club object.

http://strava.github.io/api/v3/clubs/#get-details

Parameters:club_id – The ID of the club to fetch.
Return type:stravalib.model.Club
get_club_members(club_id, limit=None)[source]

Gets the member objects for specified club ID.

http://strava.github.io/api/v3/clubs/#get-members

Parameters:
  • club_id – The numeric ID for the club.
  • limit (int) – Maximum number of athletes to return. (default unlimited)
Returns:

An iterator of stravalib.model.Athlete objects.

Return type:

BatchedResultsIterator

get_club_activities(club_id, limit=None)[source]

Gets the activities associated with specified club.

http://strava.github.io/api/v3/clubs/#get-activities

Parameters:
  • club_id – The numeric ID for the club.
  • limit (int) – Maximum number of activities to return. (default unlimited)
Returns:

An iterator of stravalib.model.Activity objects.

Return type:

BatchedResultsIterator

get_activity(activity_id)[source]

Gets specified activity.

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

http://strava.github.io/api/v3/activities/#get-details

Parameters:activity_id – The ID of activity to fetch.
Return type:stravalib.model.Activity
get_friend_activities(limit=None)[source]

Gets activities for friends (of currently authenticated athlete).

http://strava.github.io/api/v3/activities/#get-feed

Parameters:limit (int) – Maximum number of activities to return. (default unlimited)
Returns:An iterator of stravalib.model.Activity objects.
Return type:BatchedResultsIterator
create_activity(name, activity_type, start_date_local, elapsed_time, description=None, distance=None)[source]

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 – The name of the activity.
  • activity_type – The activity type (case-insensitive). Possible values: ride, run, swim, workout, hike, walk, nordicski, alpineski, backcountryski, iceskate, inlineskate, kitesurf, rollerski, windsurf, workout, snowboard, snowshoe
  • start_date (datetime.datetime or string in ISO8601 format.) – Local date/time of activity start. (TZ info will be ignored)
  • elapsed_time (datetime.timedelta or int (seconds)) – The time in seconds or a datetime.timedelta object.
  • description (str) – The description for the activity.
  • distance (units.quantity.Quantity or float (meters)) – The distance in meters (float) or a units.quantity.Quantity instance.
update_activity(activity_id, name=None, activity_type=None, private=None, commute=None, trainer=None, gear_id=None, description=None)[source]

Updates the properties of a specific activity.

http://strava.github.io/api/v3/activities/#put-updates

Parameters:
  • activity_id – The ID of the activity to update.
  • name – The name of the activity.
  • activity_type – The activity type (case-insensitive). Possible values: ride, run, swim, workout, hike, walk, nordicski, alpineski, backcountryski, iceskate, inlineskate, kitesurf, rollerski, windsurf, workout, snowboard, snowshoe
  • private – Whether the activity is private.
  • commute – Whether the activity is a commute.
  • trainer – Whether this is a trainer activity.
  • gear_id – Alpha-numeric ID of gear (bike, shoes) used on this activity.
  • description – Description for the activity.
Returns:

The updated activity.

Return type:

stravalib.model.Activity

upload_activity(activity_file, data_type, name=None, activity_type=None, private=None, external_id=None)[source]

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

http://strava.github.io/api/v3/athlete/#get-details

Parameters:
  • activity_file (file or str) – 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) if not provided, will be populated using start date and location, if available
  • 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
  • private (bool) – (optional) set to True to mark the resulting activity as private, ‘view_private’ permissions will be necessary to view the activity
  • external_id (str) – (optional) An arbitrary unique identifier may be specified which will be included in status responses.
get_activity_zones(activity_id)[source]

Gets zones for activity.

Requires premium account.

http://strava.github.io/api/v3/activities/#zones

get_activity_comments(activity_id, markdown=False, limit=None)[source]

Gets the comments for an activity.

http://strava.github.io/api/v3/comments/#list

Parameters:
  • activity_id – The activity for which to fetch comments.
  • markdown – Whether to include markdown in comments (default is false/filterout).
  • limit (int) – Max rows to return (default unlimited).
Returns:

An iterator of stravalib.model.ActivityComment objects.

Return type:

BatchedResultsIterator

get_activity_kudos(activity_id, limit=None)[source]

Gets the kudos for an activity.

http://strava.github.io/api/v3/kudos/#list

Parameters:
  • activity_id – The activity for which to fetch kudos.
  • limit (int) – Max rows to return (default unlimited).
Returns:

An iterator of stravalib.model.Athlete objects.

Return type:

BatchedResultsIterator

get_activity_photos(activity_id)[source]

Gets the photos from an activity.

http://strava.github.io/api/v3/photos/

Parameters:activity_id – The activity for which to fetch kudos.
Returns:An iterator of stravalib.model.ActivityPhoto objects.
Return type:BatchedResultsIterator
get_activity_laps(activity_id)[source]

Gets the laps from an activity.

http://strava.github.io/api/v3/activities/#laps

Parameters:activity_id – The activity for which to fetch laps.
Returns:An iterator of stravalib.model.ActivityLaps objects.
Return type:BatchedResultsIterator
get_gear(gear_id)[source]

Get details for an item of gear.

http://strava.github.io/api/v3/gear/#show

Parameters:gear_id (str) – The gear id.
Returns:The Bike or Shoe subclass object.
Return type:stravalib.model.Gear
get_segment_effort(effort_id)[source]

Return a specific segment effort by ID.

http://strava.github.io/api/v3/efforts/#retrieve

Parameters:effort_id – The id of associated effort to fetch.
Return type:stravalib.model.SegmentEffort
get_segment(segment_id)[source]

Gets a specific segment by ID.

http://strava.github.io/api/v3/segments/#retrieve

Parameters:segment_id – The segment to fetch.
Return type:stravalib.model.Segment
get_starred_segment(limit=None)[source]
Returns a summary representation of the segments starred by the
authenticated user. Pagination is supported.

http://strava.github.io/api/v3/segments/#starred

Parameters:limit (int) – (optional), limit number of starred segments returned.
Return type:stravalib.model.Segment
get_segment_leaderboard(segment_id, gender=None, age_group=None, weight_class=None, following=None, club_id=None, timeframe=None, top_results_limit=None)[source]

Gets the leaderboard for a segment.

http://strava.github.io/api/v3/segments/#leaderboard

Note that by default Strava will return the top 10 results and then will also include the bottom 5 results. The top X results can be configured by setting the top_results_limit parameter; however,the bottom 5 results are always included. (i.e. if you specify top_results_limit=15, you will get a total of 20 entries back.)

Parameters:
  • segment_id – ID of the segment.
  • gender – (optional) ‘M’ or ‘F’
  • age_group – (optional) ‘0_24’, ‘25_34’, ‘35_44’, ‘45_54’, ‘55_64’, ‘65_plus’
  • weight_class – (optional) pounds ‘0_124’, ‘125_149’, ‘150_164’, ‘165_179’, ‘180_199’, ‘200_plus’ or kilograms ‘0_54’, ‘55_64’, ‘65_74’, ‘75_84’, ‘85_94’, ‘95_plus’
  • following – (optional) Limit to athletes current user is following.
  • club_id – (optional) limit to specific club
  • timeframe – (optional) ‘this_year’, ‘this_month’, ‘this_week’, ‘today’
  • top_results_limit – (optional, strava default is 10 + 5 from end) How many of leading leaderboard entries to display. See description for why this is a little confusing.
Return type:

stravalib.model.SegmentLeaderboard

get_segment_efforts(segment_id, athlete_id=None, start_date_local=None, end_date_local=None, limit=None)[source]

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.

If no filtering parameters is provided all efforts for the segment will be returned.

Date range filtering is accomplished using an inclusive start and end time, thus 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, 2014 for a segment in San Francisco, CA can be fetched using 2014-01-01T00:00:00Z and 2014-01-01T23:59:59Z.

http://strava.github.io/api/v3/segments/#all_efforts

Parameters:
  • segment_id (int) – ID of the segment.
  • athlete_id (int) – (optional) ID of athlete.
  • start_date_local (datetime.datetime or str) – (optional) efforts before this date will be excluded. Either as ISO8601 or datetime object
  • end_date_local (datetime.datetime or str) – (optional) efforts after this date will be excluded. Either as ISO8601 or datetime object
  • top_results_limit – (optional),
Return type:

stravalib.model.SegmentEffort

explore_segments(bounds, activity_type=None, min_cat=None, max_cat=None)[source]

Returns an array of up to 10 segments.

http://strava.github.io/api/v3/segments/#explore

Parameters:
  • bounds (list of 4 floats or list 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) Minimum climb category filter
  • max_cat (int) – (optional) Maximum climb category filter
get_activity_streams(activity_id, types=None, resolution=None, series_type=None)[source]

Returns an streams for an activity.

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

http://strava.github.io/api/v3/streams/#activity

Parameters:
  • activity_id – The ID of activity.
  • types (list) – (optional) A list of the the types of streams to fetch.
  • resolution (str) – (optional, default is ‘all’) indicates desired number of data points. ‘low’ (100), ‘medium’ (1000), ‘high’ (10000) or ‘all’.
  • series_type (str) – (optional, default is ‘distance’. Relevant only if using resolution either ‘time’ or ‘distance’. Used to index the streams if the stream is being reduced.
Type:

int

Return type:

stravalib.model.Stream

get_effort_streams(effort_id, types=None, resolution=None, series_type=None)[source]

Returns an streams for an effort.

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

http://strava.github.io/api/v3/streams/#effort

Parameters:
  • effort_id – The ID of effort.
  • types (list) – (optional) A list of the the types of streams to fetch.
  • resolution (str) – (optional, default is ‘all’) indicates desired number of data points. ‘low’ (100), ‘medium’ (1000), ‘high’ (10000) or ‘all’.
  • series_type (str) – (optional, default is ‘distance’. Relevant only if using resolution either ‘time’ or ‘distance’. Used to index the streams if the stream is being reduced.
Type:

int

Return type:

stravalib.model.Stream

get_segment_streams(segment_id, types=None, resolution=None, series_type=None)[source]

Returns an streams for a segment.

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

http://strava.github.io/api/v3/streams/#effort

Parameters:
  • segment_id – The ID of segment.
  • types (list) – (optional) A list of the the types of streams to fetch.
  • resolution (str) – (optional, default is ‘all’) indicates desired number of data points. ‘low’ (100), ‘medium’ (1000), ‘high’ (10000) or ‘all’.
  • series_type (str) – (optional, default is ‘distance’. Relevant only if using resolution either ‘time’ or ‘distance’. Used to index the streams if the stream is being reduced.
Type:

int

Return type:

stravalib.model.Stream

class stravalib.client.BatchedResultsIterator(entity, result_fetcher, bind_client=None, limit=None, per_page=None)[source]

Bases: object

An iterator that enables iterating over requests that return paged results.

class stravalib.client.ActivityUploader(client, response)[source]

Bases: object

The “future” object that holds information about an activity file upload and can wait for upload to finish, etc.

update_from_repsonse(response, raise_exc=True)[source]

Updates internal state of object.

Parameters:
  • response (dict) – The response object (dict).
  • raise_exc (bool) – Whether to raise an exception if the response indicates an error state. (default True)
Raises stravalib.exc.ActivityUploadFailed:
 

If the response indicates an error and raise_exc is True.

poll()[source]

Update internal state from polling strava.com.

Raises stravalib.exc.ActivityUploadFailed:
 If the poll returns an error.
wait(timeout=None, poll_interval=1.0)[source]

Wait for the upload to complete or to err out.

Will return the resulting Activity or raise an exception if the upload fails.

Parameters:
  • timeout (float) – The max seconds to wait. Will raise TimeoutExceeded exception if this time passes without success or error response.
  • poll_interval (float) – How long to wait between upload checks. Strava recommends 1s minimum. (default 1.0s)
Returns:

The uploaded Activity object (fetched from server)

Return type:

stravalib.model.Activity

Raises:
  • stravalib.exc.TimeoutExceeded – If a timeout was specified and activity is still processing after timeout has elapsed.
  • stravalib.exc.ActivityUploadFailed – If the poll returns an error.

Model

Entity classes for representing the various Strava datatypes.

class stravalib.model.BaseEntity(**kwargs)[source]

Bases: object

A base class for all entities in the system, including objects that may not be first-class entities in Strava.

from_dict(d)[source]

Populates this object from specified dict.

Only defined attributes will be set; warnings will be logged for invalid attributes.

classmethod deserialize(v)[source]

Creates a new object based on serialized (dict) struct.

class stravalib.model.ResourceStateEntity(**kwargs)[source]

Bases: stravalib.model.BaseEntity

Mixin for entities that include the resource_state attribute.

resource_state

The detail-level for this entity.

class stravalib.model.IdentifiableEntity(**kwargs)[source]

Bases: stravalib.model.ResourceStateEntity

Mixin for entities that include an ID attribute.

id

The numeric ID for this entity.

class stravalib.model.BoundEntity(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BaseEntity

Base class for entities that support lazy loading additional data using a bound client.

bind_client = None

The stravalib.client.Client that can be used to load related resources.

classmethod deserialize(v, bind_client=None)[source]

Creates a new object based on serialized (dict) struct.

class stravalib.model.LoadableEntity(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BoundEntity, stravalib.model.IdentifiableEntity

Base class for entities that are bound and have an ID associated with them.

In theory these entities can be “expaned” by additional Client queries. In practice this is not implemented, since usefulness is limited due to resource-state limitations, etc.

expand()[source]

Expand this object with data from the bound client.

(THIS IS NOT IMPLEMENTED CURRENTLY.)

class stravalib.model.Club(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Class to represent a club.

Currently summary and detail resource states have the same attributes.

name

Name of the club.

profile_medium

URL to a 62x62 pixel club picture

profile

URL to a 124x124 pixel club picture

members[source]

An iterator of stravalib.model.Athlete members of this club.

activities[source]

An iterator of reverse-chronological stravalib.model.Activity activities for this club.

class stravalib.model.Gear(**kwargs)[source]

Bases: stravalib.model.IdentifiableEntity

id

Alpha-numeric gear ID.

name

Name athlete entered for bike (does not apply to shoes)

distance

Distance for this bike/shoes.

primary

athlete’s default bike/shoes

brand_name

Brand name of bike/shoes.

model_name

Modelname of bike/shoes.

description

Description of bike/shoe item.

classmethod deserialize(v)[source]

Creates a new object based on serialized (dict) struct.

class stravalib.model.Bike(**kwargs)[source]

Bases: stravalib.model.Gear

Represents an athlete’s bike.

frame_type

(detailed-only) Type of bike frame.

class stravalib.model.Shoe(**kwargs)[source]

Bases: stravalib.model.Gear

Represent’s an athlete’s pair of shoes.

class stravalib.model.ActivityTotals(**kwargs)[source]

Bases: stravalib.model.BaseEntity

Represent ytd/recent/all run/ride totals.

achievement_count

How many achievements

count

How many activities

distance

Total distance travelled

elapsed_time

datetime.timedelta of total elapsed time

elevation_gain

Total elevation gain

moving_time

datetime.timedelta of total moving time

class stravalib.model.Athlete(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Represents a Strava athlete.

firstname

Athlete’s first name.

lastname

Athlete’s last name.

profile_medium

URL to a 62x62 pixel profile picture

profile

URL to a 124x124 pixel profile picture

city

Athlete’s home city

state

Athlete’s home state

country

Athlete’s home country

sex

Athlete’s sex (‘M’, ‘F’ or null)

friend

‘pending’, ‘accepted’, ‘blocked’ or ‘null’ the authenticated athlete’s following status of this athlete

follower

‘pending’, ‘accepted’, ‘blocked’ or ‘null’ this athlete’s following status of the authenticated athlete

premium

Whether athlete is a premium member (true/false)

created_at

datetime.datetime when athlete record was created.

updated_at

datetime.datetime when athlete record was last updated.

approve_followers

Whether athlete has elected to approve followers

follower_count

(detailed-only) How many people are following this athlete

friend_count

(detailed-only) How many people is this athlete following

mutual_friend_count

(detailed-only) How many people are both following and being followed by this athlete

date_preference

(detailed-only) Athlete’s preferred date representation (e.g. “%m/%d/%Y”)

measurement_preference

(detailed-only) How athlete prefers to see measurements (i.e. “feet” (or what “meters”?))

email

(detailed-only) Athlete’s email address

clubs

(detailed-only) Which clubs athlete belongs to. (list of stravalib.model.Club)

bikes

(detailed-only) Which bikes this athlete owns. (list of stravalib.model.Bike)

shoes

(detailed-only) Which shoes this athlete owns. (list of stravalib.model.Shoe)

ytd_run_totals

(undocumented) Year-to-date totals for runs. (stravalib.model.ActivityTotals)

recent_run_totals

(undocumented) Recent totals for runs. (stravalib.model.ActivityTotals)

all_run_totals

(undocumented) All-time totals for runs. (stravalib.model.ActivityTotals)

ytd_ride_totals

(undocumented) Year-to-date totals for rides. (stravalib.model.ActivityTotals)

recent_ride_totals

(undocumented) Recent totals for rides. (stravalib.model.ActivityTotals)

all_ride_totals

(undocumented) All-time totals for rides. (stravalib.model.ActivityTotals)

super_user

(undocumented) Whether athlete is a super user (not

biggest_ride_distance

(undocumented) Longest ride for athlete.

biggest_climb_elevation_gain

(undocumented) Greatest single elevation gain for athlete.

email_language

The user’s preferred lang/locale (e.g. en-US)

weight

(undocumented, detailed-only) Athlete’s configured weight.

max_heartrate

(undocumented, detailed-only) Athlete’s configured max HR

username
(undocumented, detailed-only) Athlete’s username.
description
(undocumented, detailed-only) Athlete’s personal description
instagram_username
(undocumented, detailed-only) Associated instagram username
offer_in_app_payment
(undocumented, detailed-only)
global_privacy
(undocumented, detailed-only) Whether athlete has global privacy enabled.
receive_newsletter
(undocumented, detailed-only) Whether athlete has elected to receive newsletter
email_kom_lost
(undocumented, detailed-only) Whether athlete has elected to receive emails when KOMs are lost.
dateofbirth
(undocumented, detailed-only) Athlete’s date of birth
facebook_sharing_enabled
(undocumented, detailed-only) Whether Athlete has enabled sharing on Facebook
profile_original

(undocumented, detailed-only)

premium_expiration_date
(undocumented, detailed-only) When does premium membership expire (int unix epoch)
email_send_follower_notices

(undocumented, detailed-only)

plan

(undocumented, detailed-only)

agreed_to_terms

(undocumented, detailed-only) Whether athlete has agreed to terms

follower_request_count

(undocumented, detailed-only) How many people have requested to follow this athlete

email_facebook_twitter_friend_joins

(undocumented, detailed-only) Whether athlete has elected to receve emails when a twitter or facebook friend joins Strava

receive_kudos_emails

(undocumented, detailed-only) Whether athlete has elected to receive emails on kudos

receive_follower_feed_emails

(undocumented, detailed-only) Whether athlete has elected to receive emails on new followers

receive_comment_emails

(undocumented, detailed-only) Whether athlete has elected to receive emails on activity comments

friends[source]

Iterator of stravalib.model.Athlete objects for this activity.

followers[source]

Iterator of stravalib.model.Athlete objects for this activity.

class stravalib.model.ActivityKudos(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

activity kudos are a subset of athlete properties.

firstname

Athlete’s first name.

lastname

Athlete’s last name.

profile_medium

URL to a 62x62 pixel profile picture

profile

URL to a 124x124 pixel profile picture

city

Athlete’s home city

state

Athlete’s home state

country

Athlete’s home country

sex

Athlete’s sex (‘M’, ‘F’ or null)

friend

‘pending’, ‘accepted’, ‘blocked’ or ‘null’ the authenticated athlete’s following status of this athlete

follower

‘pending’, ‘accepted’, ‘blocked’ or ‘null’ this athlete’s following status of the authenticated athlete

premium

Whether athlete is a premium member (true/false)

created_at

datetime.datetime when athlete record was created.

updated_at

datetime.datetime when athlete record was last updated.

approve_followers

Whether athlete has elected to approve followers

class stravalib.model.Split(**kwargs)[source]

Bases: stravalib.model.BaseEntity

A split – may be metric or standard units (which has no bearing on the units used in this object, just the binning of values).

distance

Distance for this split

elapsed_time

datetime.timedelta of elapsed time for split

elevation_difference

Elevation difference for split

moving_time

datetime.timedelta of moving time for split

average_heartrate

Average HR for split

split

Which split number

class stravalib.model.SegmentExplorerResult(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Represents a segment result from the segment explorer feature.

(These are not full segment objects, but the segment object can be fetched via the ‘segment’ property of this object.)

id

ID of the segment.

name

Name of the segment

climb_category

Climb category for the segment (0 is higher)

climb_category_desc

Climb category text

avg_grade

Average grade for segment.

start_latlng

Start lat/lon for segment

end_latlng

End lat/lon for segment

elev_difference

Total elevation difference over segment.

distance

Distance of segment.

points

Encoded Google polyline of points in segment

segment[source]

Associated (full) stravalib.model.Segment object.

class stravalib.model.Segment(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Represents a single Strava segment.

name

Name of the segment.

activity_type

Activity type of segment (‘Ride’ or ‘Run’)

distance

Distance of segment

average_grade

Average grade (%) for segment

maximum_grade

Maximum grade (%) for segment

elevation_high

The highest point of the segment.

elevation_low

The lowest point of the segment.

start_latlng

The start lat/lon (tuple)

end_latlng

The end lat/lon (tuple)

start_latitude

The start latitude (float)

end_latitude

The end latitude (float)

start_longitude

The start longitude (float)

end_longitude

The end longitude (float)

city

The city this segment is in.

state

The state this segment is in.

country

The country this segment is in.

private

Whether this is a private segment.

starred

Whether this segment is starred by authenticated athlete

created_at

datetime.datetime when was segment created.

updated_at

datetime.datetime when was segment last updated.

total_elevation_gain

What is total elevation gain for segment.

map

stravalib.model.Map object for segment.

effort_count

How many times has this segment been ridden.

athlete_count

How many athletes have ridden this segment

hazardous

Whether this segment has been flagged as hazardous

star_count

number of stars on this segment.

leaderboard[source]

The stravalib.model.SegmentLeaderboard object for this segment.

class stravalib.model.BaseEffort(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Base class for a best effort or segment effort.

name

The name of the segment

segment

The associated stravalib.model.Segment for this effort

activity

The associated stravalib.model.Activity

athlete

The associated stravalib.model.Athlete

kom_rank

1-10 segment KOM ranking for athlete at time of upload

pr_rank

1-3 personal record ranking for athlete at time of upload

moving_time

datetime.timedelta

elapsed_time

datetime.timedelta

start_date

datetime.datetime when effort was started in GMT

start_date_local

datetime.datetime when effort was started in activity timezone for this effort

distance

The distance for this effort.

average_watts

Average power during effort

average_heartrate

Average HR during effort

max_heartrate

Max HR during effort

average_cadence

Average cadence during effort

class stravalib.model.BestEffort(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BaseEffort

Class representing a best effort (e.g. best time for 5k)

class stravalib.model.SegmentEffort(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BaseEffort

Class representing a best effort on a particular segment.

class stravalib.model.Activity(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Represents an activity (ride, run, etc.).

guid

(undocumented)

external_id

An external ID for the activity (relevant when specified during upload).

upload_id

The upload ID for an activit.

athlete

The associated stravalib.model.Athlete that performed this activity.

name

The name of the activity.

distance

The distance for the activity.

moving_time

The moving time duration for this activity.

elapsed_time

The total elapsed time (including stopped time) for this activity.

total_elevation_gain

Total elevation gain for activity.

type

The activity type.

start_date

datetime.datetime when activity was started in GMT

start_date_local

datetime.datetime when activity was started in activity timezone

timezone

The timezone for activity.

start_latlng

The start location (lat/lon tuple)

end_latlng

The end location (lat/lon tuple)

location_city

The activity location city

location_state

The activity location state

location_country

The activity location state

start_latitude

The start latitude

start_longitude

The start longitude

achievement_count

How many achievements earned for the activity

kudos_count

How many kudos received for activity

comment_count

How many comments for activity.

athlete_count

How many other athlete’s participated in activity

photo_count

How many photos linked to activity

map

stravavlib.model.Map of activity.

trainer

Whether activity was performed on a stationary trainer.

commute

Whether activity is a commute.

manual

Whether activity was manually entered.

private

Whether activity is private

flagged

Whether activity was flagged.

gear_id

Which bike/shoes were used on activity.

average_speed

Average speed for activity.

max_speed

Max speed for activity

truncated

Only present if activity is owned by authenticated athlete, set to 0 if not truncated by privacy zones

has_kudoed

If authenticated user has kudoed this activity

best_efforts

list of metric stravalib.model.BestEffort summaries

segment_efforts

list of stravalib.model.SegmentEffort efforts for activity.

splits_metric

list of metric stravalib.model.Split summaries (running activities only)

splits_standard

list of standard/imperial stravalib.model.Split summaries (running activities only)

average_watts

(undocumented) Average power during activity

average_heartrate

(undocumented) Average HR during activity

max_heartrate

(undocumented) Max HR during activity

average_cadence

(undocumented) Average cadence during activity

kilojoules

(undocumented) Kilojoules of energy used during activity

average_temp

(undocumented) Average temperature (when available from device) during activity.

calories

Calculation of how many calories burned on activity

description

(undocumented) Description of activity.

workout_type

(undocumented)

comments[source]

Iterator of stravalib.model.ActivityComment objects for this activity.

laps[source]

Iterator of stravalib.model.ActivityLap objects for this activity.

zones[source]

list of stravalib.model.ActivityZone objects for this activity.

kudos[source]

list of stravalib.model.ActivityKudos objects for this activity.

photos[source]

list of stravalib.model.ActivityPhoto objects for this activity.

class stravalib.model.SegmentLeaderboardEntry(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BoundEntity

Represents a single entry on a segment leaderboard.

The stravalib.model.SegmentLeaderboard object is essentially a collection of instances of this class.

effort_id

The numeric ID for the segment effort.

athlete_id

The numeric ID for the athlete.

athlete_name

The athlete’s name.

athlete_gender

The athlete’s sex (M/F)

athlete_profile

Link to athlete profile photo

average_hr

The athlete’s average HR for this effort

average_watts

The athlete’s average power for this effort

distance

The distance for this effort.

elapsed_time

The elapsed time for this effort

moving_time

The moving time for this effort

start_date

datetime.datetime when this effot was started in GMT

start_date_local

datetime.datetime when this effort was started in activity timezone

activity_id

The numeric ID of the associated activity for this effort.

rank

The rank on the leaderboard.

athlete[source]

The related stravalib.model.Athlete (performs additional server fetch).

activity[source]

The related stravalib.model.Activity (performs additional server fetch).

effort[source]

The related stravalib.model.SegmentEffort (performs additional server fetch).

class stravalib.model.SegmentLeaderboard(bind_client=None, **kwargs)[source]

Bases: _abcoll.Sequence, stravalib.model.BoundEntity

The ranked leaderboard for a segment.

This class is effectively a collection of stravalib.model.SegmentLeaderboardEntry objects.

class stravalib.model.DistributionBucket(**kwargs)[source]

Bases: stravalib.model.BaseEntity

A single distribution bucket object, used for activity zones.

max

Max datatpoint

min

Min datapoint

time

Time in seconds (not a datetime.timedelta)

class stravalib.model.BaseActivityZone(bind_client=None, **kwargs)[source]

Bases: stravalib.model.LoadableEntity

Base class for activity zones.

A collection of stravalib.model.DistributionBucket objects.

distribution_buckets

The collection of stravalib.model.DistributionBucket objects

type

Type of activity zone (heartrate, power, pace).

sensor_based

Whether zone data is sensor-based (as opposed to calculated)

classmethod deserialize(v, bind_client=None)[source]

Creates a new object based on serialized (dict) struct.

class stravalib.model.HeartrateActivityZone(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BaseActivityZone

Activity zone for heart rate.

score

The score (suffer score) for this HR zone.

points

The points for this HR zone.

custom_zones

Whether athlete has setup custom zones.

max

The max heartrate

class stravalib.model.PaceActivityZone(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BaseActivityZone

Activity zone for pace.

score

The score for this zone.

sample_race_distance

(Not sure?)

sample_race_time

(Not sure?)

class stravalib.model.PowerActivityZone(bind_client=None, **kwargs)[source]

Bases: stravalib.model.BaseActivityZone

Activity zone for power.

bike_weight

Weight of bike being used (factored into power calculations)

athlete_weight

Weight of athlete (factored into power calculations)

Errors

The exception classes raised by the library.

exception stravalib.exc.LoginRequired[source]

Login is required to perform specified action.

exception stravalib.exc.UnboundEntity[source]

Exception used to indicate that a model Entity is not bound to client instances.

exception stravalib.exc.Fault[source]

Container for exceptions raised by the remote server.

exception stravalib.exc.RateLimitExceeded[source]

Exception raised when the client rate limit has been exceeded.

http://strava.github.io/api/#access

Under-the-Hood

This part of the documentation describes the under-the-hood implementation of the model.

(TODO)

Table Of Contents

Previous topic

Athletes

This Page