javastrava.api.v3.service

Interface ActivityService

All Superinterfaces:

StravaService

All Known Implementing Classes:

ActivityServiceImpl

public interface ActivityService
extends StravaService

StravaActivity related services

Author:

Dan Shannon

See Also:

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

Method Summary

Modifier and Type	Method and Description
StravaComment	createComment(Integer activityId, String text) Create a comment on an activity.
StravaActivity	createManualActivity(StravaActivity activity) This API endpoint is for creating manually entered activities.
StravaActivity	deleteActivity(Integer id) Deletes the identified StravaActivity
void	deleteComment(Integer activityId, Integer commentId) Delete a comment belonging to the authenticated user
void	deleteComment(StravaComment comment) Delete a comment belonging to the authenticated user
StravaActivity	getActivity(Integer id) StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.
StravaActivity	getActivity(Integer id, Boolean includeAllEfforts) StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.
void	giveKudos(Integer activityId) Kudo an activity (kudo is given by the authenticated athlete).
List<StravaComment>	listActivityComments(Integer id) Comments on an activity can be viewed by any user.
List<StravaComment>	listActivityComments(Integer id, Boolean markdown) Comments on an activity can be viewed by any user.
List<StravaComment>	listActivityComments(Integer id, Boolean markdown, Paging pagingInstruction) Comments on an activity can be viewed by any user.
List<StravaComment>	listActivityComments(Integer id, Paging pagingInstruction) Comments on an activity can be viewed by any user.
List<StravaAthlete>	listActivityKudoers(Integer id) A kudos is Strava's version of a 'like' or '+1'.
List<StravaAthlete>	listActivityKudoers(Integer id, Paging pagingInstruction) A kudos is Strava's version of a 'like' or '+1'.
List<StravaLap>	listActivityLaps(Integer id) This resource will return all laps for an activity.
List<StravaPhoto>	listActivityPhotos(Integer id) Photos are external objects associated with an activity.
List<StravaActivityZone>	listActivityZones(Integer id) Heartrate and power zones are set by the athlete.
List<StravaComment>	listAllActivityComments(Integer activityId) List ALL comments on an activity, regardless of how many there are
List<StravaAthlete>	listAllActivityKudoers(Integer activityId) List ALL kudoers on an activity, regardless of how many there are
List<StravaActivity>	listAllAuthenticatedAthleteActivities() This endpoint returns a list of activities for the authenticated StravaAthlete.
List<StravaActivity>	listAllAuthenticatedAthleteActivities(Calendar before, Calendar after) This endpoint returns a list of activities for the authenticated StravaAthlete.
List<StravaActivity>	listAllFriendsActivities() List the recent activities performed by those the current authenticated StravaAthlete is following.
List<StravaActivity>	listAllRelatedActivities(Integer activityId) List ALL related activities, regardless of how many there are
List<StravaActivity>	listAuthenticatedAthleteActivities() This endpoint returns a list of activities for the authenticated StravaAthlete.
List<StravaActivity>	listAuthenticatedAthleteActivities(Calendar before, Calendar after) This endpoint returns a list of activities for the authenticated StravaAthlete.
List<StravaActivity>	listAuthenticatedAthleteActivities(Calendar before, Calendar after, Paging pagingInstruction) This endpoint returns a list of activities for the authenticated StravaAthlete.
List<StravaActivity>	listAuthenticatedAthleteActivities(Paging pagingInstruction) This endpoint returns a list of activities for the authenticated StravaAthlete.
List<StravaActivity>	listFriendsActivities() List the recent activities performed by those the current authenticated StravaAthlete is following.
List<StravaActivity>	listFriendsActivities(Paging pagingInstruction) List the recent activities performed by those the current authenticated StravaAthlete is following.
List<StravaActivity>	listRelatedActivities(Integer id) Returns the activities that were matched as "with this group".
List<StravaActivity>	listRelatedActivities(Integer id, Paging pagingInstruction) Returns the activities that were matched as "with this group".
StravaActivity	updateActivity(Integer id, StravaActivityUpdate activity) Requires write permissions, as requested during the authorization process.

Method Detail

getActivity

StravaActivity getActivity(Integer id)

StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.

By default, only "important" efforts are included. "Importance" is based on a number of undocumented factors and its value may change over time. Factors considered include: segment age, views and stars, if the user has hidden/shown the segment and if the effort was a PR. Note, if two activities cover the same segment, it is possible that for one activity the associated effort is "important" but not for the other.

Note that effort ids may exceed the max value for 32-bit integers. A long integer type should be used.

Each segment effort will have a hidden attribute indicating if it is "important" or not.

Returns null if the activity does not exist

URL GET https://www.strava.com/api/v3/activities/:id

Parameters:

id - The id of the activity to be returned

Returns:

Returns a detailed representation if the activity is owned by the requesting athlete. Returns a summary representation for all other requests.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

getActivity

StravaActivity getActivity(Integer id,
                           Boolean includeAllEfforts)

StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.

By default, only "important" efforts are included. "Importance" is based on a number of factors and its value may change over time. Factors considered include: segment age, views and stars, if the user has hidden/shown the segment and if the effort was a PR. Note, if two activities cover the same segment, it is possible that for one activity the associated effort is "important" but not for the other.

Note that effort ids may exceed the max value for 32-bit integers. A long integer type should be used.

Each segment effort will have a hidden attribute indicating if it is "important" or not.

Returns null if the activity does not exist

URL GET https://www.strava.com/api/v3/activities/:id

Parameters:

id - The id of the activity to be returned

includeAllEfforts - (Optional) Used to include all segment efforts in the result (if omitted or false then only "important" efforts are returned).

Returns:

Returns a detailed representation if the activity is owned by the requesting athlete. Returns a summary representation for all other requests.

See Also:

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

createManualActivity

StravaActivity createManualActivity(StravaActivity activity)

This API endpoint is for creating manually entered activities. To upload a FIT, TCX or GPX file see the Upload Documentation.

Requires write permissions, as requested during the authorization process.

Only updates name, activity type, startDateLocal, elapsedTime, description and distance.

If any other activity attributes are passed to the API, they are ignored when creating the activity.

If successful, returns a 201 status code along with a detailed representation of the created activity.

URL POST https://www.strava.com/api/v3/activities

Parameters:

activity - The activity to be uploaded

Returns:

The activity as it was uploaded on Strava

Throws:

UnauthorizedException - If user's security token is invalid or does not grant write access to the activity

See Also:

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

updateActivity

StravaActivity updateActivity(Integer id,
                              StravaActivityUpdate activity)

Requires write permissions, as requested during the authorization process.

Only updates name, type, private, commute, trainer, gear_id and description

Returns null if the activity doesn't exist on Strava

URL PUT https://www.strava.com/api/v3/activities/:id

Parameters:

id - The identifier of the activity to be updated

activity - The StravaActivityUpdate to be updated

Returns:

Returns a detailed representation of the updated StravaActivity.

Throws:

UnauthorizedException - If the service's security token is invalid or doesn't grant write access to this activity

See Also:

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

deleteActivity

StravaActivity deleteActivity(Integer id)

Deletes the identified StravaActivity

Requires write permissions, as requested during the authorization process.

Returns null if the activity does not exist on Strava

URL DELETE https://www.strava.com/api/v3/activities/:id

Parameters:

id - The id of the StravaActivity to be deleted.

Returns:

Should return null

Throws:

UnauthorizedException - If the service's security token is invalid or doesn't grant write access to this activity

See Also:

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

listAllAuthenticatedAthleteActivities

List<StravaActivity> listAllAuthenticatedAthleteActivities()

This endpoint returns a list of activities for the authenticated StravaAthlete.

Pagination is NOT supported. USE WITH CAUTION. ALL activities for the athlete will be returned, regardless of how many calls to the Strava API are required to achieve this.

URL GET https://www.strava.com/api/v3/athlete/activities

Returns:

Returns an array of StravaActivity summary representations sorted newest first by default.

Throws:

UnauthorizedException - thrown if service's security token is invalid

See Also:

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

listAllAuthenticatedAthleteActivities

List<StravaActivity> listAllAuthenticatedAthleteActivities(Calendar before,
                                                           Calendar after)

This endpoint returns a list of activities for the authenticated StravaAthlete.

Pagination is NOT supported. USE WITH CAUTION. ALL activities for the athlete will be returned, regardless of how many calls to the Strava API are required to achieve this.

URL GET https://www.strava.com/api/v3/athlete/activities

Parameters:

before - Return only rides started BEFORE this date/time

after - Return only rides started AFTER this data/time

Returns:

Returns an array of StravaActivity summary representations sorted newest first by default.

Throws:

UnauthorizedException - thrown if service's security token is invalid

See Also:

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

listAuthenticatedAthleteActivities

List<StravaActivity> listAuthenticatedAthleteActivities()

This endpoint returns a list of activities for the authenticated StravaAthlete.

URL GET https://www.strava.com/api/v3/athlete/activities

Pagination is not supported. Returns only the first page of activities.

Returns:

Returns an array of StravaActivity summary representations sorted newest first by default.

Throws:

UnauthorizedException - thrown if service's security token is invalid

See Also:

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

listAuthenticatedAthleteActivities

List<StravaActivity> listAuthenticatedAthleteActivities(Paging pagingInstruction)

This endpoint returns a list of activities for the authenticated StravaAthlete.

URL GET https://www.strava.com/api/v3/athlete/activities

Pagination is supported

Parameters:

pagingInstruction - (Optional) The page to be returned

Returns:

Returns an array of StravaActivity summary representations sorted newest first by default. Will be sorted oldest first if the after parameter is used.

Throws:

UnauthorizedException - thrown if service's security token is invalid

See Also:

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

listAuthenticatedAthleteActivities

List<StravaActivity> listAuthenticatedAthleteActivities(Calendar before,
                                                        Calendar after)

This endpoint returns a list of activities for the authenticated StravaAthlete.

Pagination is not supported. Returns only the first page of activities.

URL GET https://www.strava.com/api/v3/athlete/activities

Parameters:

before - (Optional) result will start with activities whose start_date is before this value

after - (Optional) result will start with activities whose start_date is after this value, sorted oldest first

Returns:

Returns an array of StravaActivity summary representations sorted newest first by default. Will be sorted oldest first if the after parameter is used.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listAuthenticatedAthleteActivities

List<StravaActivity> listAuthenticatedAthleteActivities(Calendar before,
                                                        Calendar after,
                                                        Paging pagingInstruction)

This endpoint returns a list of activities for the authenticated StravaAthlete.

Should be used with before, after or page/per_page. Using a combination will result in an error or unexpected results.

Pagination is supported.

URL GET https://www.strava.com/api/v3/athlete/activities

Parameters:

before - (Optional) result will start with activities whose start_date is before this value

after - (Optional) result will start with activities whose start_date is after this value, sorted oldest first

pagingInstruction - (Optional) The page to be returned

Returns:

Returns an array of StravaActivity summary representations sorted newest first by default. Will be sorted oldest first if the after parameter is used.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listFriendsActivities

List<StravaActivity> listFriendsActivities(Paging pagingInstruction)

List the recent activities performed by those the current authenticated StravaAthlete is following.

Pagination is supported. However, results are limited to the last 200 total activities.

URL GET https://www.strava.com/api/v3/activities/following

Parameters:

pagingInstruction - (Optional) The page to be returned

Returns:

Returns an array of activity summary representations sorted newest first by start_date.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listFriendsActivities

List<StravaActivity> listFriendsActivities()

List the recent activities performed by those the current authenticated StravaAthlete is following.

Pagination is not supported. Only the first page is returned by Strava.

URL GET https://www.strava.com/api/v3/activities/following

Returns:

Returns an array of activity summary representations sorted newest first by start_date.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listAllFriendsActivities

List<StravaActivity> listAllFriendsActivities()

List the recent activities performed by those the current authenticated StravaAthlete is following.

Pagination is not supported - this method just returns ALL friends' activities (although it is restricted by Strava to the last 200)

USE WITH CAUTION - ACTIVITIES WITH MANY RELATED ACTIVITIES WILL REQUIRE MANY CALLS TO THE STRAVA API

URL GET https://www.strava.com/api/v3/activities/following

Returns:

Returns an array of activity summary representations sorted newest first by start_date.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityZones

List<StravaActivityZone> listActivityZones(Integer id)

Heartrate and power zones are set by the athlete. This endpoint returns the time (seconds) in each zone for the activity.

The distribution is not customizable.

Requires an access token associated with the owner of the activity and the owner must be a premium user.

Returns null if the activity does not exist

Pagination is not supported. Returns all activity zones for the activity.

URL GET https://www.strava.com/api/v3/activities/:id/zones

Parameters:

id - The id of the activity for which zones should be returned

Returns:

Returns an array of activity zones for the StravaActivity identified

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityLaps

List<StravaLap> listActivityLaps(Integer id)

This resource will return all laps for an activity. Laps are triggered by athletes using their respective devices, such as Garmin watches.

Returns null if the activity does not exist

Pagination is not supported. Returns all the laps for the activity.

URL GET https://www.strava.com/api/v3/activities/:id/laps

Parameters:

id - The id of the StravaActivity for which laps should be returned

Returns:

Returns an array of lap effort summaries

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityComments

List<StravaComment> listActivityComments(Integer id,
                                         Boolean markdown)

Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.

StravaComment posting can be enabled on a per application basis, email developers -at- strava.com for more information.

The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.

Pagination is not supported. Only the first page is returned by Strava.

Returns null if the StravaActivity does not exist

Returns an empty array if the StravaActivity does not contain any comments

Pagination is not supported. Returns only the first page of activities.

URL GET https://www.strava.com/api/v3/activities/:id/comments

Parameters:

id - The id of the StravaActivity for which comments should be returned

markdown - (Optional) Include markdown in comments (default is false - i.e. filter out

Returns:

List of comments

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityComments

List<StravaComment> listActivityComments(Integer id)

Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.

Comment posting can be enabled on a per application basis, email developers -at- strava.com for more information.

The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.

Pagination is not supported. Only the first page is returned by Strava.

Returns null if the StravaActivity does not exist

Returns an empty array if the StravaActivity does not contain any comments

URL GET https://www.strava.com/api/v3/activities/:id/comments

Parameters:

id - The id of the StravaActivity for which comments should be returned

Returns:

List of comments

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityComments

List<StravaComment> listActivityComments(Integer id,
                                         Paging pagingInstruction)

Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.

Comment posting can be enabled on a per application basis, email developers -at- strava.com for more information.

The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.

Pagination is supported.

Returns null if the StravaActivity does not exist

Returns an empty array if the StravaActivity does not contain any comments

URL GET https://www.strava.com/api/v3/activities/:id/comments

Parameters:

id - The id of the StravaActivity for which comments should be returned

pagingInstruction - (Optional) Paging instructions. If not provided then the first page is returned.

Returns:

List of comments

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityComments

List<StravaComment> listActivityComments(Integer id,
                                         Boolean markdown,
                                         Paging pagingInstruction)

Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.

StravaComment posting can be enabled on a per application basis, email developers -at- strava.com for more information.

The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.

Pagination is supported.

Returns null if the StravaActivity does not exist

Returns an empty array if the StravaActivity does not contain any comments

URL GET https://www.strava.com/api/v3/activities/:id/comments

Parameters:

id - The id of the StravaActivity for which comments should be returned

markdown - (Optional) Include markdown in comments (default is false - i.e. filter out

pagingInstruction - (Optional) The page to be returned

Returns:

List of comments

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityKudoers

List<StravaAthlete> listActivityKudoers(Integer id)

A kudos is Strava's version of a 'like' or '+1'. The number of kudos on an activity is returned with the activity summary.

Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.

The number of kudos is included in the activity summary and detailed representations. This endpoint is for retrieving more detailed information on the athletes who have left kudos and can only be accessed by the owner of the activity.

Returns null if the StravaActivity does not exist

Pagination is not supported. Only the first page is returned by Strava.

Parameters:

id - The id of the StravaActivity for which kudoers are to be listed

Returns:

Returns an array of athlete summary objects.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityKudoers

List<StravaAthlete> listActivityKudoers(Integer id,
                                        Paging pagingInstruction)

A kudos is Strava's version of a 'like' or '+1'. The number of kudos on an activity is returned with the activity summary.

Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.

The number of kudos is included in the activity summary and detailed representations. This endpoint is for retrieving more detailed information on the athletes who have left kudos and can only be accessed by the owner of the activity.

Returns null if the StravaActivity does not exist

Pagination is supported.

Parameters:

id - The id of the StravaActivity for which kudoers are to be listed

pagingInstruction - (Optional) The page to be returned

Returns:

Returns an array of athlete summary objects.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listActivityPhotos

List<StravaPhoto> listActivityPhotos(Integer id)

Photos are external objects associated with an activity. Currently, the only external photo source is Instagram.

Note that Instagram does not provide taken_at information.

The number of photos is included in the activity summary and detail responses. Use this endpoint to retrieve a list of photos associated with this activity. This endpoint can only be accessed by the owner of the activity.

Returns null if the StravaActivity does not exist

Pagination is not supported. Returns all photos associated with the activity.

URL GET https://www.strava.com/api/v3/activities/:id/photos

Parameters:

id - The id of the StravaActivity for which photos are to be listed

Returns:

Returns an array of photo objects.

Throws:

UnauthorizedException - If the service's security token is invalid

See Also:

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

listRelatedActivities

List<StravaActivity> listRelatedActivities(Integer id)

Returns the activities that were matched as "with this group". The number equals activity.athlete_count-1.

Returns null if the StravaActivity does not exist

Pagination is not supported. Only the first page is returned by Strava.

Parameters:

id - StravaActivity id for which related activities should be listed

Returns:

List of related activities (not including the main activity)

Throws:

UnauthorizedException - If the service's security token is invalid

listRelatedActivities

List<StravaActivity> listRelatedActivities(Integer id,
                                           Paging pagingInstruction)

Returns the activities that were matched as "with this group". The number equals activity.athlete_count-1.

Returns null if the StravaActivity does not exist

Pagination is supported.

Parameters:

id - StravaActivity id for which related activities should be listed

pagingInstruction - Paging instructions

Returns:

List of related activities (not including the main activity)

Throws:

UnauthorizedException - If the service's security token is invalid

createComment

StravaComment createComment(Integer activityId,
                            String text)
                     throws NotFoundException,
                            BadRequestException

Create a comment on an activity.

Comment posting must be explicitly authorised by Strava for your application.

The comment will be made by the user associated with the access_token.

URL POST https://www.strava.com/api/v3/activities/:id/comments

Parameters:

activityId - Activity identifier

text - Comment text

Returns:

The comment as created on Strava

Throws:

NotFoundException - if the activity does not exist

BadRequestException - if the comment is invalid

deleteComment

void deleteComment(Integer activityId,
                   Integer commentId)
            throws NotFoundException

Delete a comment belonging to the authenticated user

Parameters:

commentId - Identifier of the comment to be deleted

activityId - Identifier of the activity the comment was posted to

Throws:

NotFoundException - if the activity or the comment does exist

deleteComment

void deleteComment(StravaComment comment)
            throws NotFoundException

Delete a comment belonging to the authenticated user

Parameters:

comment - The comment to be deleted

Throws:

NotFoundException - If the comment does not exist on Strava

giveKudos

void giveKudos(Integer activityId)
        throws NotFoundException

Kudo an activity (kudo is given by the authenticated athlete). You can do this multiple times, but the activity only receives one kudos.

Parameters:

activityId - Identifier of the activity to be kudoed.

Throws:

NotFoundException - If the activity does not exist on Strava

listAllActivityComments

List<StravaComment> listAllActivityComments(Integer activityId)

List ALL comments on an activity, regardless of how many there are

Returns null if the activity does not exist

Pagination is not supported - this method just returns ALL comments

USE WITH CAUTION - ACTIVITIES WITH MANY COMMENTS WILL REQUIRE MANY CALLS TO THE STRAVA API

Parameters:

activityId - The activity whose comments should be listed

Returns:

All comments on the activity

listAllActivityKudoers

List<StravaAthlete> listAllActivityKudoers(Integer activityId)

List ALL kudoers on an activity, regardless of how many there are

Returns null if the activity does not exist

Pagination is not supported - this method just returns ALL kudoers

USE WITH CAUTION - ACTIVITIES WITH MANY KUDOS WILL REQUIRE MANY CALLS TO THE STRAVA API

Parameters:

activityId - The activity whose kudoers should be listed

Returns:

All athletes who have kudoed the activity

listAllRelatedActivities

List<StravaActivity> listAllRelatedActivities(Integer activityId)

List ALL related activities, regardless of how many there are

Returns null if the activity does not exist

Pagination is not supported - this method just returns ALL related activities

USE WITH CAUTION - ACTIVITIES WITH MANY RELATED ACTIVITIES WILL REQUIRE MANY CALLS TO THE STRAVA API

Parameters:

activityId - The activity identifier

Returns:

List of Strava activities that Strava has determined are related to this one