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
StravaClub	getClub(Integer id)
StravaSegment	getSegment(Integer id)
StravaSegmentLeaderboard	getSegmentLeaderboard(Integer id, StravaGender gender, StravaAgeGroup ageGroup, StravaWeightClass weightClass, Boolean following, Integer clubId, StravaLeaderboardDateRange dateRange, Integer page, Integer perPage, Integer contextEntries)
StravaSegment[]	listAuthenticatedAthleteStarredSegments(Integer page, Integer perPage)
StravaSegmentEffort[]	listSegmentEfforts(Integer id, Integer athleteId, String start, String end, Integer page, Integer perPage)
StravaSegment[]	listStarredSegments(Integer id, Integer page, Integer perPage)
StravaSegmentExplorerResponse	segmentExplore(String bounds, StravaSegmentExplorerActivityType activityType, StravaClimbCategory minCategory, StravaClimbCategory maxCategory)

Method Detail

getClub

@GET(value="/clubs/{id}")
StravaClub getClub(@Path(value="id")
                                              Integer id)
                                       throws NotFoundException

Parameters:

id - Club identifier

Returns:

Club details

Throws:

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

See Also:

ClubService.getClub(java.lang.Integer)

getSegment

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

Parameters:

id - The unique identifier of the segment

Returns:

The Segment

Throws:

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

listAuthenticatedAthleteStarredSegments

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

Parameters:

page - (optional) Page number to be returned

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

Returns:

An array of segments

See Also:

SegmentService.listAuthenticatedAthleteStarredSegments(javastrava.util.Paging)

listStarredSegments

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

Parameters:

id - 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

listSegmentEfforts

@GET(value="/segments/{id}/all_efforts")
StravaSegmentEffort[] listSegmentEfforts(@Path(value="id")
                                                                                   Integer id,
                                                                                   @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

Parameters:

id - 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

See Also:

SegmentService.listSegmentEfforts(Integer, Integer, java.util.Calendar, java.util.Calendar, javastrava.util.Paging)

getSegmentLeaderboard

@GET(value="/segments/{id}/leaderboard")
StravaSegmentLeaderboard getSegmentLeaderboard(@Path(value="id")
                                                                                         Integer id,
                                                                                         @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

Parameters:

id - 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

See Also:

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

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)