javastrava.api.v3.service

Interface SegmentService

All Superinterfaces:

StravaService

All Known Implementing Classes:

SegmentServiceImpl

public interface SegmentService
extends StravaService

Segments are specific sections of road.

Athletes' efforts are compared on these segments and leaderboards are created.

Author:

Dan Shannon

Method Summary

Modifier and Type	Method and Description
StravaSegmentLeaderboard	getAllSegmentLeaderboard(Integer segmentId) Leaderboards represent the ranking of athletes on specific segments.
StravaSegmentLeaderboard	getAllSegmentLeaderboard(Integer segmentId, StravaGender gender, StravaAgeGroup ageGroup, StravaWeightClass weightClass, Boolean following, Integer clubId, StravaLeaderboardDateRange dateRange) Leaderboards represent the ranking of athletes on specific segments.
StravaSegment	getSegment(Integer id) Retrieve details about a specific segment.
StravaSegmentLeaderboard	getSegmentLeaderboard(Integer id) Leaderboards represent the ranking of athletes on specific segments.
StravaSegmentLeaderboard	getSegmentLeaderboard(Integer id, Paging pagingInstruction) Leaderboards represent the ranking of athletes on specific segments.
StravaSegmentLeaderboard	getSegmentLeaderboard(Integer id, StravaGender gender, StravaAgeGroup ageGroup, StravaWeightClass weightClass, Boolean following, Integer clubId, StravaLeaderboardDateRange dateRange, Paging pagingInstruction, Integer contextEntries) Leaderboards represent the ranking of athletes on specific segments.
List<StravaSegment>	listAllAuthenticatedAthleteStarredSegments() Returns a summary representation of ALL the segments starred by the authenticated athlete.
List<StravaSegmentEffort>	listAllSegmentEfforts(Integer segmentId) Retrieve an array of segment efforts, for a given StravaSegment.
List<StravaSegmentEffort>	listAllSegmentEfforts(Integer segmentId, Integer athleteId, Calendar startDate, Calendar endDate) Retrieve an array of segment efforts, for a given StravaSegment, filtered by StravaAthlete and/or a date range.
List<StravaSegment>	listAllStarredSegments(Integer athleteId) Returns a summary representation of ALL the segments starred by the identified athlete.
List<StravaSegment>	listAuthenticatedAthleteStarredSegments() Returns a summary representation of the segments starred by the authenticated athlete.
List<StravaSegment>	listAuthenticatedAthleteStarredSegments(Paging pagingInstruction) Returns a summary representation of the segments starred by the authenticated athlete.
List<StravaSegmentEffort>	listSegmentEfforts(Integer id) Retrieve an array of segment efforts, for a given StravaSegment.
List<StravaSegmentEffort>	listSegmentEfforts(Integer id, Integer athleteId, Calendar startDateLocal, Calendar endDateLocal) Retrieve an array of segment efforts, for a given StravaSegment, filtered by StravaAthlete and/or a date range.
List<StravaSegmentEffort>	listSegmentEfforts(Integer id, Integer athleteId, Calendar startDateLocal, Calendar endDateLocal, Paging pagingInstruction) Retrieve an array of segment efforts, for a given StravaSegment, filtered by StravaAthlete and/or a date range.
List<StravaSegmentEffort>	listSegmentEfforts(Integer id, Paging pagingInstruction) Retrieve an array of segment efforts, for a given StravaSegment.
List<StravaSegment>	listStarredSegments(Integer id) Returns a summary representation of the segments starred by the identified athlete.
List<StravaSegment>	listStarredSegments(Integer id, Paging pagingInstruction) Returns a summary representation of the segments starred by the identified athlete.
StravaSegmentExplorerResponse	segmentExplore(StravaMapPoint southwestCorner, StravaMapPoint northeastCorner, StravaSegmentExplorerActivityType activityType, StravaClimbCategory minCat, StravaClimbCategory maxCat) This endpoint can be used to find popular segments within a given area (defined by the southwest and northeast corners of the area).

Method Detail

getSegment

StravaSegment getSegment(Integer id)

Retrieve details about a specific segment.

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

Returns null if the segment does not exist

Parameters:

id - The id of the StravaSegment to be retrieved

Returns:

Returns a detailed representation of the StravaSegment.

Throws:

UnauthorizedException - If authorisation fails

See Also:

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

listAuthenticatedAthleteStarredSegments

List<StravaSegment> listAuthenticatedAthleteStarredSegments(Paging pagingInstruction)

Returns a summary representation of the segments starred by the authenticated athlete.

Pagination is supported.

URL GET https://www.strava.com/api/v3/segments/starred

Parameters:

pagingInstruction - (Optional) paging instructions

Returns:

Returns a summary representation of the segments starred by the authenticated StravaAthlete.

See Also:

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

listAuthenticatedAthleteStarredSegments

List<StravaSegment> listAuthenticatedAthleteStarredSegments()

Returns a summary representation of the segments starred by the authenticated athlete.

Pagination is NOT supported. Returns only the first page of segments.

URL GET https://www.strava.com/api/v3/segments/starred

Returns:

Returns a summary representation of the segments starred by the authenticated StravaAthlete.

See Also:

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

listStarredSegments

List<StravaSegment> listStarredSegments(Integer id,
                                        Paging pagingInstruction)

Returns a summary representation of the segments starred by the identified athlete.

Pagination is supported.

Returns null if the athlete with the given id does not exist.

URL GET https://www.strava.com/api/v3/segments/starred

Parameters:

id - Identifier of the StravaAthlete for which starred segments are to be returned

pagingInstruction - (Optional) paging instructions

Returns:

Returns a summary representation of the segments starred by the identified StravaAthlete.

See Also:

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

listStarredSegments

List<StravaSegment> listStarredSegments(Integer id)

Returns a summary representation of the segments starred by the identified athlete.

Pagination is NOT supported. Returns only the first page of segments

Returns null if the athlete with the given id does not exist.

URL GET https://www.strava.com/api/v3/segments/starred

Parameters:

id - Identifier of the StravaAthlete for which starred segments are to be returned

Returns:

Returns a summary representation of the segments starred by the identified StravaAthlete.

See Also:

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

listSegmentEfforts

List<StravaSegmentEffort> listSegmentEfforts(Integer id,
                                             Integer athleteId,
                                             Calendar startDateLocal,
                                             Calendar endDateLocal,
                                             Paging pagingInstruction)

Retrieve an array of segment efforts, for a given StravaSegment, filtered by StravaAthlete and/or a date range.

Filtering parameters, like athlete_id, start_date_local and end_date_local, are optional. If they are not 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.

Pagination is supported.

Returns null if the segment does not exist.

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

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

startDateLocal - (Optional) ISO 8601 formatted date time

endDateLocal - (Optional) ISO 8601 formatted date time

pagingInstruction - (Optional) Page to start at for pagination / number of results 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.

See Also:

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

listSegmentEfforts

List<StravaSegmentEffort> listSegmentEfforts(Integer id,
                                             Integer athleteId,
                                             Calendar startDateLocal,
                                             Calendar endDateLocal)

Retrieve an array of segment efforts, for a given StravaSegment, filtered by StravaAthlete and/or a date range.

Filtering parameters, like athlete_id, start_date_local and end_date_local, are optional. If they are not 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.

Pagination is NOT supported. Returns only the first page of segment efforts.

Returns null if the segment does not exist.

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

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

startDateLocal - (Optional) ISO 8601 formatted date time

endDateLocal - (Optional) ISO 8601 formatted date time

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.

See Also:

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

listSegmentEfforts

List<StravaSegmentEffort> listSegmentEfforts(Integer id,
                                             Paging pagingInstruction)

Retrieve an array of segment efforts, for a given StravaSegment.

Pagination is supported.

Returns null if the segment does not exist.

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

Parameters:

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

pagingInstruction - (Optional) paging parameters

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.

See Also:

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

listSegmentEfforts

List<StravaSegmentEffort> listSegmentEfforts(Integer id)

Retrieve an array of segment efforts, for a given StravaSegment.

Pagination is NOT supported. Returns only the first page of segment efforts.

Returns null if the segment does not exist.

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

Parameters:

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

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.

See Also:

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

getSegmentLeaderboard

StravaSegmentLeaderboard getSegmentLeaderboard(Integer id,
                                               StravaGender gender,
                                               StravaAgeGroup ageGroup,
                                               StravaWeightClass weightClass,
                                               Boolean following,
                                               Integer clubId,
                                               StravaLeaderboardDateRange dateRange,
                                               Paging pagingInstruction,
                                               Integer contextEntries)

Leaderboards represent the ranking of athletes on specific segments.

Filter by age_group and weight_class is only allowed if the authenticated athlete is a Strava premium member.

Pagination is supported.

Returns null if the segment does not exist.

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

Parameters:

id - The id of the segment to return a leaderboard for

gender - (Optional) StravaGender to filter results by

ageGroup - (Optional) Age group to filter results by

weightClass - (Optional) Weight class to filter results by

following - (Optional) If true then will return only results for athletes that the currently authenticated athlete is following

clubId - (Optional) Id of StravaClub to filter results by

dateRange - (Optional) Use to set to return results for this year, this month, this week etc.

pagingInstruction - (Optional) Page to start at for pagination

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

Returns:

Returns an array of up to 10, by default, leaderboard entry objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated, use entry_count instead.

See Also:

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

getSegmentLeaderboard

StravaSegmentLeaderboard getSegmentLeaderboard(Integer id,
                                               Paging pagingInstruction)

Leaderboards represent the ranking of athletes on specific segments.

Filter by age_group and weight_class is only allowed if the authenticated athlete is a Strava premium member.

Pagination is supported.

Returns null if the segment does not exist.

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

Parameters:

id - The id of the segment to return a leaderboard for

pagingInstruction - (Optional) Page number, Number of results per page (max 200)

Returns:

Returns an array of up to 10, by default, leaderboard entry objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated, use entry_count instead.

See Also:

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

getSegmentLeaderboard

StravaSegmentLeaderboard getSegmentLeaderboard(Integer id)

Leaderboards represent the ranking of athletes on specific segments.

Filter by age_group and weight_class is only allowed if the authenticated athlete is a Strava premium member.

Pagination is NOT supported. Returns only the first page of leaderboard entries.

Returns null if the segment does not exist.

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

Parameters:

id - The id of the segment to return a leaderboard for

Returns:

Returns an array of up to 10, by default, leaderboard entry objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated, use entry_count instead.

See Also:

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

segmentExplore

StravaSegmentExplorerResponse segmentExplore(StravaMapPoint southwestCorner,
                                             StravaMapPoint northeastCorner,
                                             StravaSegmentExplorerActivityType activityType,
                                             StravaClimbCategory minCat,
                                             StravaClimbCategory maxCat)

This endpoint can be used to find popular segments within a given area (defined by the southwest and northeast corners of the area).

Pagination is not supported. Returns up to 10 segments only.

URL GET https://www.strava.com/api/v3/segments/explore

Parameters:

southwestCorner - The southwest corner of the area to be explored

northeastCorner - The northeast corner of the area to be explored

activityType - (Optional) "running" or "riding", default is riding

minCat - (Optional) Minimum climb category filter

maxCat - (Optional) Maximum climb category filter

Returns:

Returns an array of up to 10 segment objects

See Also:

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

listAllAuthenticatedAthleteStarredSegments

List<StravaSegment> listAllAuthenticatedAthleteStarredSegments()

Returns a summary representation of ALL the segments starred by the authenticated athlete.

Pagination is NOT supported.

URL GET https://www.strava.com/api/v3/segments/starred

Returns:

Returns a summary representation of the segments starred by the authenticated StravaAthlete.

See Also:

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

listAllStarredSegments

List<StravaSegment> listAllStarredSegments(Integer athleteId)

Returns a summary representation of ALL the segments starred by the identified athlete.

Pagination is NOT supported. Returns ALL starred segments.

Returns null if the athlete with the given id does not exist.

URL GET https://www.strava.com/api/v3/segments/starred

Parameters:

athleteId - Identifier of the StravaAthlete for which starred segments are to be returned

Returns:

Returns a summary representation of the segments starred by the identified StravaAthlete.

See Also:

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

getAllSegmentLeaderboard

StravaSegmentLeaderboard getAllSegmentLeaderboard(Integer segmentId)

Leaderboards represent the ranking of athletes on specific segments.

Pagination is NOT supported. Returns THE ENTIRE leaderboard.

Returns null if the segment does not exist.

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

Parameters:

segmentId - The id of the segment to return a leaderboard for

Returns:

Returns an array of up to 10, by default, leaderboard entry objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated, use entry_count instead.

See Also:

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

getAllSegmentLeaderboard

StravaSegmentLeaderboard getAllSegmentLeaderboard(Integer segmentId,
                                                  StravaGender gender,
                                                  StravaAgeGroup ageGroup,
                                                  StravaWeightClass weightClass,
                                                  Boolean following,
                                                  Integer clubId,
                                                  StravaLeaderboardDateRange dateRange)

Leaderboards represent the ranking of athletes on specific segments.

Filter by age_group and weight_class is only allowed if the authenticated athlete is a Strava premium member.

Pagination is NOT supported. Returns the ENTIRE leaderboard.

Returns null if the segment does not exist.

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

Parameters:

segmentId - The id of the segment to return a leaderboard for

gender - (Optional) StravaGender to filter results by

ageGroup - (Optional) Age group to filter results by

weightClass - (Optional) Weight class to filter results by

following - (Optional) If true then will return only results for athletes that the currently authenticated athlete is following

clubId - (Optional) Id of StravaClub to filter results by

dateRange - (Optional) Use to set to return results for this year, this month, this week etc.

Returns:

Returns an the entire set of leaderboard entry objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated, use entry_count instead.

See Also:

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

listAllSegmentEfforts

List<StravaSegmentEffort> listAllSegmentEfforts(Integer segmentId)

Retrieve an array of segment efforts, for a given StravaSegment.

Pagination is NOT supported. Returns ALL segment efforts.

Returns null if the segment does not exist.

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

Parameters:

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

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.

See Also:

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

listAllSegmentEfforts

List<StravaSegmentEffort> listAllSegmentEfforts(Integer segmentId,
                                                Integer athleteId,
                                                Calendar startDate,
                                                Calendar endDate)

Retrieve an array of segment efforts, for a given StravaSegment, filtered by StravaAthlete and/or a date range.

Filtering parameters, like athlete_id, start_date_local and end_date_local, are optional. If they are not 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.

Pagination is NOT supported. All segment efforts will be returned.

Returns null if the segment does not exist.

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

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

startDate - (Optional) ISO 8601 formatted date time

endDate - (Optional) ISO 8601 formatted date time

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.

See Also:

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