javastrava.api.v3.rest

Interface SegmentAPI

public interface SegmentAPI

API definitions for the SegmentService Strava endpoints

Author:

Dan Shannon

Method Summary

Modifier and Type	Method and Description
StravaSegment	getSegment(Integer segmentId)
void	getSegment(Integer segmentId, StravaAPICallback<StravaSegment> callback)
StravaSegmentLeaderboard	getSegmentLeaderboard(Integer segmentId, StravaGender gender, StravaAgeGroup ageGroup, StravaWeightClass weightClass, Boolean following, Integer clubId, StravaLeaderboardDateRange dateRange, Integer page, Integer perPage, Integer contextEntries)
void	getSegmentLeaderboard(Integer segmentId, StravaGender gender, StravaAgeGroup ageGroup, StravaWeightClass weightClass, Boolean following, Integer clubId, StravaLeaderboardDateRange dateRange, Integer page, Integer perPage, Integer contextEntries, StravaAPICallback<StravaSegmentLeaderboard> callback)
StravaSegment[]	listAuthenticatedAthleteStarredSegments(Integer page, Integer perPage)
void	listAuthenticatedAthleteStarredSegments(Integer page, Integer perPage, StravaAPICallback<StravaSegment[]> callback)
StravaSegmentEffort[]	listSegmentEfforts(Integer segmentId, Integer athleteId, String start, String end, Integer page, Integer perPage)
void	listSegmentEfforts(Integer segmentId, Integer athleteId, String start, String end, Integer page, Integer perPage, StravaAPICallback<StravaSegmentEffort[]> callback)
StravaSegment[]	listStarredSegments(Integer athleteId, Integer page, Integer perPage)
void	listStarredSegments(Integer athleteId, Integer page, Integer perPage, StravaAPICallback<StravaSegment[]> callback)
StravaSegmentExplorerResponse	segmentExplore(String bounds, StravaSegmentExplorerActivityType activityType, StravaClimbCategory minCategory, StravaClimbCategory maxCategory)
void	segmentExplore(String bounds, StravaSegmentExplorerActivityType activityType, StravaClimbCategory minCategory, StravaClimbCategory maxCategory, StravaAPICallback<StravaSegmentExplorerResponse> callback)

Method Detail

getSegment

@GET(value="/segments/{id}")
StravaSegment getSegment(@Path(value="id")
                                                       Integer segmentId)
                                                throws NotFoundException

Parameters:

segmentId - The unique identifier of the segment

Returns:

The Segment

Throws:

NotFoundException - If the segment with the given id does not exist

See Also:

SegmentService.getSegment(java.lang.Integer)

getSegment

@GET(value="/segments/{id}")
void getSegment(@Path(value="id")
                                              Integer segmentId,
                                              StravaAPICallback<StravaSegment> callback)
                                       throws NotFoundException

Parameters:

segmentId - The unique identifier of the segment

callback - The callback to execute on completion

Throws:

NotFoundException - If the segment with the given id does not exist

See Also:

SegmentService.getSegment(java.lang.Integer)

getSegmentLeaderboard

@GET(value="/segments/{id}/leaderboard")
StravaSegmentLeaderboard getSegmentLeaderboard(@Path(value="id")
                                                                                         Integer segmentId,
                                                                                         @Query(value="gender")
                                                                                         StravaGender gender,
                                                                                         @Query(value="age_group")
                                                                                         StravaAgeGroup ageGroup,
                                                                                         @Query(value="weight_class")
                                                                                         StravaWeightClass weightClass,
                                                                                         @Query(value="following")
                                                                                         Boolean following,
                                                                                         @Query(value="club_id")
                                                                                         Integer clubId,
                                                                                         @Query(value="date_range")
                                                                                         StravaLeaderboardDateRange dateRange,
                                                                                         @Query(value="page")
                                                                                         Integer page,
                                                                                         @Query(value="per_page")
                                                                                         Integer perPage,
                                                                                         @Query(value="context_entries")
                                                                                         Integer contextEntries)
                                                                                  throws NotFoundException,
                                                                                         BadRequestException

Parameters:

segmentId - Segment identifier

gender - (Optional) Gender to filter the leaderboard by

ageGroup - (Optional) Age group to filter the leaderboard by

weightClass - (Optional) Weight class to filter the leaderboard by

following - (Optional) If true then filter leaderboard by athletes the authenticated athlete is following

clubId - (Optional) Club to filter the leaderboard by

dateRange - (Optional) Date range (this year, this month etc.) to filter the leaderboard by

page - (Optional) Page number to return (default is 1)

perPage - (Optional) Page size to return (default is 50)

contextEntries - (Optional) Number of context entries to return either side of the authenticated athlete (default is 2, maximum is 15)

Returns:

A Strava leaderboard

Throws:

NotFoundException - If the segment with the given id doesn't exist

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.getSegmentLeaderboard(Integer, StravaGender, StravaAgeGroup, StravaWeightClass, Boolean, Integer, StravaLeaderboardDateRange, javastrava.util.Paging, Integer)

getSegmentLeaderboard

@GET(value="/segments/{id}/leaderboard")
void getSegmentLeaderboard(@Path(value="id")
                                                                     Integer segmentId,
                                                                     @Query(value="gender")
                                                                     StravaGender gender,
                                                                     @Query(value="age_group")
                                                                     StravaAgeGroup ageGroup,
                                                                     @Query(value="weight_class")
                                                                     StravaWeightClass weightClass,
                                                                     @Query(value="following")
                                                                     Boolean following,
                                                                     @Query(value="club_id")
                                                                     Integer clubId,
                                                                     @Query(value="date_range")
                                                                     StravaLeaderboardDateRange dateRange,
                                                                     @Query(value="page")
                                                                     Integer page,
                                                                     @Query(value="per_page")
                                                                     Integer perPage,
                                                                     @Query(value="context_entries")
                                                                     Integer contextEntries,
                                                                     StravaAPICallback<StravaSegmentLeaderboard> callback)
                                                              throws NotFoundException,
                                                                     BadRequestException

Parameters:

segmentId - Segment identifier

gender - (Optional) Gender to filter the leaderboard by

ageGroup - (Optional) Age group to filter the leaderboard by

weightClass - (Optional) Weight class to filter the leaderboard by

following - (Optional) If true then filter leaderboard by athletes the authenticated athlete is following

clubId - (Optional) Club to filter the leaderboard by

dateRange - (Optional) Date range (this year, this month etc.) to filter the leaderboard by

page - (Optional) Page number to return (default is 1)

perPage - (Optional) Page size to return (default is 50)

contextEntries - (Optional) Number of context entries to return either side of the authenticated athlete (default is 2, maximum is 15)

callback - The callback to execute on completion

Throws:

NotFoundException - If the segment with the given id doesn't exist

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.getSegmentLeaderboard(Integer, StravaGender, StravaAgeGroup, StravaWeightClass, Boolean, Integer, StravaLeaderboardDateRange, javastrava.util.Paging, Integer)

listAuthenticatedAthleteStarredSegments

@GET(value="/segments/starred")
StravaSegment[] listAuthenticatedAthleteStarredSegments(@Query(value="page")
                                                                                         Integer page,
                                                                                         @Query(value="per_page")
                                                                                         Integer perPage)
                                                                                  throws BadRequestException

Parameters:

page - (optional) Page number to be returned

perPage - (optional) Number of entries to return per page

Returns:

An array of segments

Throws:

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.listAuthenticatedAthleteStarredSegments(javastrava.util.Paging)

listAuthenticatedAthleteStarredSegments

@GET(value="/segments/starred")
void listAuthenticatedAthleteStarredSegments(@Query(value="page")
                                                                              Integer page,
                                                                              @Query(value="per_page")
                                                                              Integer perPage,
                                                                              StravaAPICallback<StravaSegment[]> callback)
                                                                       throws BadRequestException

Parameters:

page - (optional) Page number to be returned

perPage - (optional) Number of entries to return per page

callback - The callback to execute on completion

Throws:

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.listAuthenticatedAthleteStarredSegments(javastrava.util.Paging)

listSegmentEfforts

@GET(value="/segments/{id}/all_efforts")
StravaSegmentEffort[] listSegmentEfforts(@Path(value="id")
                                                                                   Integer segmentId,
                                                                                   @Query(value="athlete_id")
                                                                                   Integer athleteId,
                                                                                   @Query(value="start_date_local")
                                                                                   String start,
                                                                                   @Query(value="end_date_local")
                                                                                   String end,
                                                                                   @Query(value="page")
                                                                                   Integer page,
                                                                                   @Query(value="per_page")
                                                                                   Integer perPage)
                                                                            throws NotFoundException,
                                                                                   BadRequestException

Parameters:

segmentId - The id of the StravaSegment for which segment efforts are to be returned

athleteId - (Optional) id of the StravaAthlete to filter results by

start - (Optional) ISO 8601 formatted date time

end - (Optional) ISO 8601 formatted date time

page - (optional) Page number to be returned

perPage - (optional) Number of entries to return per page

Returns:

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

Throws:

NotFoundException - If the segment with the given id doesn't exist

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.listSegmentEfforts(Integer, Integer, LocalDateTime, LocalDateTime, javastrava.util.Paging)

listSegmentEfforts

@GET(value="/segments/{id}/all_efforts")
void listSegmentEfforts(@Path(value="id")
                                                                  Integer segmentId,
                                                                  @Query(value="athlete_id")
                                                                  Integer athleteId,
                                                                  @Query(value="start_date_local")
                                                                  String start,
                                                                  @Query(value="end_date_local")
                                                                  String end,
                                                                  @Query(value="page")
                                                                  Integer page,
                                                                  @Query(value="per_page")
                                                                  Integer perPage,
                                                                  StravaAPICallback<StravaSegmentEffort[]> callback)
                                                           throws NotFoundException,
                                                                  BadRequestException

Parameters:

segmentId - The id of the StravaSegment for which segment efforts are to be returned

athleteId - (Optional) id of the StravaAthlete to filter results by

start - (Optional) ISO 8601 formatted date time

end - (Optional) ISO 8601 formatted date time

page - (optional) Page number to be returned

perPage - (optional) Number of entries to return per page

callback - The callback to execute on completion

Throws:

NotFoundException - If the segment with the given id doesn't exist

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.listSegmentEfforts(Integer, Integer, LocalDateTime, LocalDateTime, javastrava.util.Paging)

listStarredSegments

@GET(value="/athletes/{id}/segments/starred")
StravaSegment[] listStarredSegments(@Path(value="id")
                                                                                   Integer athleteId,
                                                                                   @Query(value="page")
                                                                                   Integer page,
                                                                                   @Query(value="per_page")
                                                                                   Integer perPage)
                                                                            throws NotFoundException,
                                                                                   BadRequestException

Parameters:

athleteId - The id of the athlete whose starred segments are to be retrieved

page - (optional) Page number to be returned

perPage - (optional) Number of entries to return per page

Returns:

An array of segments

Throws:

NotFoundException - If the segment with the given id does not exist

UnauthorizedException - If there is a security or privacy violation

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.listStarredSegments(java.lang.Integer, Paging)

listStarredSegments

@GET(value="/athletes/{id}/segments/starred")
void listStarredSegments(@Path(value="id")
                                                                        Integer athleteId,
                                                                        @Query(value="page")
                                                                        Integer page,
                                                                        @Query(value="per_page")
                                                                        Integer perPage,
                                                                        StravaAPICallback<StravaSegment[]> callback)
                                                                 throws NotFoundException,
                                                                        BadRequestException

Parameters:

athleteId - The id of the athlete whose starred segments are to be retrieved

page - (optional) Page number to be returned

perPage - (optional) Number of entries to return per page

callback - The callback to execute on completion

Throws:

NotFoundException - If the segment with the given id does not exist

UnauthorizedException - If there is a security or privacy violation

BadRequestException - If the paging instructions are invalid

See Also:

SegmentService.listStarredSegments(java.lang.Integer, Paging)

segmentExplore

@GET(value="/segments/explore")
StravaSegmentExplorerResponse segmentExplore(@Query(value="bounds")
                                                                              String bounds,
                                                                              @Query(value="activity_type")
                                                                              StravaSegmentExplorerActivityType activityType,
                                                                              @Query(value="min_cat")
                                                                              StravaClimbCategory minCategory,
                                                                              @Query(value="max_cat")
                                                                              StravaClimbCategory maxCategory)

Parameters:

bounds - Pair of co-ordinates defining a box which is to be searched for segments

activityType - (Optional) Activity type to filter by (default is 'ride')

minCategory - (Optional) Minimum climb category for which rides should be returned

maxCategory - (Optional) Maximum climb category for which rides should be returned

Returns:

A response full of slightly weird-looking segments

See Also:

SegmentService.segmentExplore(javastrava.api.v3.model.StravaMapPoint, javastrava.api.v3.model.StravaMapPoint, StravaSegmentExplorerActivityType, StravaClimbCategory, StravaClimbCategory)

segmentExplore

@GET(value="/segments/explore")
void segmentExplore(@Query(value="bounds")
                                                     String bounds,
                                                     @Query(value="activity_type")
                                                     StravaSegmentExplorerActivityType activityType,
                                                     @Query(value="min_cat")
                                                     StravaClimbCategory minCategory,
                                                     @Query(value="max_cat")
                                                     StravaClimbCategory maxCategory,
                                                     StravaAPICallback<StravaSegmentExplorerResponse> callback)

Parameters:

bounds - Pair of co-ordinates defining a box which is to be searched for segments

activityType - (Optional) Activity type to filter by (default is 'ride')

minCategory - (Optional) Minimum climb category for which rides should be returned

maxCategory - (Optional) Maximum climb category for which rides should be returned

callback - The callback to execute on completion

See Also:

SegmentService.segmentExplore(javastrava.api.v3.model.StravaMapPoint, javastrava.api.v3.model.StravaMapPoint, StravaSegmentExplorerActivityType, StravaClimbCategory, StravaClimbCategory)