javastrava.service.SegmentService Maven / Gradle / Ivy
Show all versions of javastrava-api Show documentation
package javastrava.service;
import java.time.LocalDateTime;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import javastrava.model.StravaAthlete;
import javastrava.model.StravaClub;
import javastrava.model.StravaMapPoint;
import javastrava.model.StravaSegment;
import javastrava.model.StravaSegmentEffort;
import javastrava.model.StravaSegmentExplorerResponse;
import javastrava.model.StravaSegmentLeaderboard;
import javastrava.model.StravaSegmentLeaderboardEntry;
import javastrava.model.reference.StravaAgeGroup;
import javastrava.model.reference.StravaClimbCategory;
import javastrava.model.reference.StravaGender;
import javastrava.model.reference.StravaLeaderboardDateRange;
import javastrava.model.reference.StravaResourceState;
import javastrava.model.reference.StravaSegmentExplorerActivityType;
import javastrava.model.reference.StravaWeightClass;
import javastrava.service.exception.UnauthorizedException;
import javastrava.util.Paging;
/**
*
* {@link StravaSegment Segments} are specific sections of road.
*
*
*
* {@link StravaAthlete Athletes'} {@link StravaSegmentEffort efforts} are compared on these segments and {@link StravaSegmentLeaderboard leaderboards} are created.
*
*
* @author Dan Shannon
*
*/
public interface SegmentService extends StravaService {
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment segments}.
*
*
*
* USE WITH CAUTION - POPULAR SEGMENTS CAN HAVE TENS OF THOUSANDS OF ATHLETES ON THE LEADERBOARD, REQUIRING A VERY LARGE NUMBER OF CALLS TO THE STRAVA API
*
*
*
* 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public StravaSegmentLeaderboard getAllSegmentLeaderboard(final Integer segmentId);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @param gender
* (Optional) {@link StravaGender StravaGender} to filter results by
* @param ageGroup
* (Optional) {@link StravaAgeGroup Age group} to filter results by
* @param weightClass
* (Optional) {@link StravaWeightClass Weight class} to filter results by
* @param following
* (Optional) If true then will return only results for {@link StravaAthlete athletes} that the currently authenticated athlete is following
* @param clubId
* (Optional) Id of {@link StravaClub} to filter results by
* @param dateRange
* (Optional) Use to set to return results for this year, this month, this week etc.
* @return Returns an the entire set of {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated,
* use entry_count instead.
*/
public StravaSegmentLeaderboard getAllSegmentLeaderboard(final Integer segmentId, final StravaGender gender, final StravaAgeGroup ageGroup, final StravaWeightClass weightClass,
final Boolean following, final Integer clubId, final StravaLeaderboardDateRange dateRange);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment segments}.
*
*
*
* USE WITH CAUTION - POPULAR SEGMENTS CAN HAVE TENS OF THOUSANDS OF ATHLETES ON THE LEADERBOARD, REQUIRING A VERY LARGE NUMBER OF CALLS TO THE STRAVA API
*
*
*
* 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public CompletableFuture getAllSegmentLeaderboardAsync(final Integer segmentId);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @param gender
* (Optional) {@link StravaGender StravaGender} to filter results by
* @param ageGroup
* (Optional) {@link StravaAgeGroup Age group} to filter results by
* @param weightClass
* (Optional) {@link StravaWeightClass Weight class} to filter results by
* @param following
* (Optional) If true then will return only results for {@link StravaAthlete athletes} that the currently authenticated athlete is following
* @param clubId
* (Optional) Id of {@link StravaClub} to filter results by
* @param dateRange
* (Optional) Use to set to return results for this year, this month, this week etc.
* @return Returns an the entire set of {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is deprecated,
* use entry_count instead.
*/
public CompletableFuture getAllSegmentLeaderboardAsync(final Integer segmentId, final StravaGender gender, final StravaAgeGroup ageGroup,
final StravaWeightClass weightClass, final Boolean following, final Integer clubId, final StravaLeaderboardDateRange dateRange);
/**
*
* Retrieve details about a specific {@link StravaSegment segment}.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/:id
*
*
*
* Returns null if the segment does not exist
*
*
* @see http://strava.github.io/api/v3/segments/#retrieve
*
* @param segmentId
* The id of the {@link StravaSegment} to be retrieved
* @return Returns a {@link StravaResourceState#DETAILED detailed representation} of the {@link StravaSegment}.
* @throws UnauthorizedException
* If authorisation fails
*/
public StravaSegment getSegment(final Integer segmentId);
/**
*
* Retrieve details about a specific {@link StravaSegment segment}.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/:id
*
*
*
* Returns null if the segment does not exist
*
*
* @see http://strava.github.io/api/v3/segments/#retrieve
*
* @param segmentId
* The id of the {@link StravaSegment} to be retrieved
* @return Returns a {@link StravaResourceState#DETAILED detailed representation} of the {@link StravaSegment}.
* @throws UnauthorizedException
* If authorisation fails
*/
public CompletableFuture getSegmentAsync(final Integer segmentId);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public StravaSegmentLeaderboard getSegmentLeaderboard(final Integer segmentId);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @param pagingInstruction
* (Optional) Page number, Number of results per page (max 200)
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public StravaSegmentLeaderboard getSegmentLeaderboard(final Integer segmentId, final Paging pagingInstruction);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @param gender
* (Optional) {@link StravaGender StravaGender} to filter results by
* @param ageGroup
* (Optional) {@link StravaAgeGroup Age group} to filter results by
* @param weightClass
* (Optional) {@link StravaWeightClass Weight class} to filter results by
* @param following
* (Optional) If true then will return only results for {@link StravaAthlete athletes} that the currently authenticated athlete is following
* @param clubId
* (Optional) Id of {@link StravaClub} to filter results by
* @param dateRange
* (Optional) Use to set to return results for this year, this month, this week etc.
* @param pagingInstruction
* (Optional) Page to start at for pagination
* @param contextEntries
* (Optional) number of entries to return as athlete context either side of the athlete (default is 2, maximum is 15)
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public StravaSegmentLeaderboard getSegmentLeaderboard(final Integer segmentId, final StravaGender gender, final StravaAgeGroup ageGroup, final StravaWeightClass weightClass,
final Boolean following, final Integer clubId, final StravaLeaderboardDateRange dateRange, final Paging pagingInstruction, final Integer contextEntries);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public CompletableFuture getSegmentLeaderboardAsync(final Integer segmentId);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @param pagingInstruction
* (Optional) Page number, Number of results per page (max 200)
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public CompletableFuture getSegmentLeaderboardAsync(final Integer segmentId, final Paging pagingInstruction);
/**
*
* {@link StravaSegmentLeaderboard Leaderboards} represent the ranking of {@link StravaAthlete athletes} on specific {@link StravaSegment 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
*
*
* @see http://strava.github.io/api/v3/segments/#leaderboard
*
* @param segmentId
* The id of the segment to return a leaderboard for
* @param gender
* (Optional) {@link StravaGender StravaGender} to filter results by
* @param ageGroup
* (Optional) {@link StravaAgeGroup Age group} to filter results by
* @param weightClass
* (Optional) {@link StravaWeightClass Weight class} to filter results by
* @param following
* (Optional) If true then will return only results for {@link StravaAthlete athletes} that the currently authenticated athlete is following
* @param clubId
* (Optional) Id of {@link StravaClub} to filter results by
* @param dateRange
* (Optional) Use to set to return results for this year, this month, this week etc.
* @param pagingInstruction
* (Optional) Page to start at for pagination
* @param contextEntries
* (Optional) number of entries to return as athlete context either side of the athlete (default is 2, maximum is 15)
* @return Returns an array of up to 10, by default, {@link StravaSegmentLeaderboardEntry leaderboard entry} objects. Note that effort ids should be considered 64-bit integers and effort_count is
* deprecated, use entry_count instead.
*/
public CompletableFuture getSegmentLeaderboardAsync(final Integer segmentId, final StravaGender gender, final StravaAgeGroup ageGroup,
final StravaWeightClass weightClass, final Boolean following, final Integer clubId, final StravaLeaderboardDateRange dateRange, final Paging pagingInstruction,
final Integer contextEntries);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of ALL the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete athlete}.
*
*
*
* Pagination is NOT supported.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/starred
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete}.
*/
public List listAllAuthenticatedAthleteStarredSegments();
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of ALL the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete athlete}.
*
*
*
* Pagination is NOT supported.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/starred
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete}.
*/
public CompletableFuture> listAllAuthenticatedAthleteStarredSegmentsAsync();
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public List listAllSegmentEfforts(final Integer segmentId);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}, filtered by {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param athleteId
* (Optional) id of the {@link StravaAthlete} to filter results by
* @param startDate
* (Optional) ISO 8601 formatted date time
* @param endDate
* (Optional) ISO 8601 formatted date time
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public List listAllSegmentEfforts(final Integer segmentId, final Integer athleteId, final LocalDateTime startDate, final LocalDateTime endDate);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public CompletableFuture> listAllSegmentEffortsAsync(final Integer segmentId);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}, filtered by {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param athleteId
* (Optional) id of the {@link StravaAthlete} to filter results by
* @param startDate
* (Optional) ISO 8601 formatted date time
* @param endDate
* (Optional) ISO 8601 formatted date time
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public CompletableFuture> listAllSegmentEffortsAsync(final Integer segmentId, final Integer athleteId, final LocalDateTime startDate, final LocalDateTime endDate);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of ALL the {@link StravaSegment segments} starred by the identified {@link StravaAthlete 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
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param athleteId
* Identifier of the {@link StravaAthlete} for which starred {@link StravaSegment segments} are to be returned
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete}.
*/
public List listAllStarredSegments(final Integer athleteId);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of ALL the {@link StravaSegment segments} starred by the identified {@link StravaAthlete 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
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param athleteId
* Identifier of the {@link StravaAthlete} for which starred {@link StravaSegment segments} are to be returned
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete}.
*/
public CompletableFuture> listAllStarredSegmentsAsync(final Integer athleteId);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete athlete}.
*
*
*
* Pagination is NOT supported. Returns only the first page of segments.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/starred
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete}.
*/
public List listAuthenticatedAthleteStarredSegments();
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete athlete}.
*
*
*
* Pagination is supported.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/starred
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param pagingInstruction
* (Optional) paging instructions
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete}.
*/
public List listAuthenticatedAthleteStarredSegments(final Paging pagingInstruction);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete athlete}.
*
*
*
* Pagination is NOT supported. Returns only the first page of segments.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/starred
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete}.
*/
public CompletableFuture> listAuthenticatedAthleteStarredSegmentsAsync();
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete athlete}.
*
*
*
* Pagination is supported.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/starred
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param pagingInstruction
* (Optional) paging instructions
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the authenticated {@link StravaAthlete}.
*/
public CompletableFuture> listAuthenticatedAthleteStarredSegmentsAsync(final Paging pagingInstruction);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public List listSegmentEfforts(final Integer segmentId);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}, filtered by {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param athleteId
* (Optional) id of the {@link StravaAthlete} to filter results by
* @param startDateLocal
* (Optional) ISO 8601 formatted date time
* @param endDateLocal
* (Optional) ISO 8601 formatted date time
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public List listSegmentEfforts(final Integer segmentId, final Integer athleteId, final LocalDateTime startDateLocal, final LocalDateTime endDateLocal);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}, filtered by {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param athleteId
* (Optional) id of the {@link StravaAthlete} to filter results by
* @param startDateLocal
* (Optional) ISO 8601 formatted date time
* @param endDateLocal
* (Optional) ISO 8601 formatted date time
* @param pagingInstruction
* (Optional) Page to start at for pagination / number of results per page
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public List listSegmentEfforts(final Integer segmentId, final Integer athleteId, final LocalDateTime startDateLocal, final LocalDateTime endDateLocal,
final Paging pagingInstruction);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if the segment does not exist.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/:id/all_efforts
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param pagingInstruction
* (Optional) paging parameters
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public List listSegmentEfforts(final Integer segmentId, final Paging pagingInstruction);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public CompletableFuture> listSegmentEffortsAsync(final Integer segmentId);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}, filtered by {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param athleteId
* (Optional) id of the {@link StravaAthlete} to filter results by
* @param startDateLocal
* (Optional) ISO 8601 formatted date time
* @param endDateLocal
* (Optional) ISO 8601 formatted date time
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public CompletableFuture> listSegmentEffortsAsync(final Integer segmentId, final Integer athleteId, final LocalDateTime startDateLocal, final LocalDateTime endDateLocal);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}, filtered by {@link 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
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param athleteId
* (Optional) id of the {@link StravaAthlete} to filter results by
* @param startDateLocal
* (Optional) ISO 8601 formatted date time
* @param endDateLocal
* (Optional) ISO 8601 formatted date time
* @param pagingInstruction
* (Optional) Page to start at for pagination / number of results per page
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public CompletableFuture> listSegmentEffortsAsync(final Integer segmentId, final Integer athleteId, final LocalDateTime startDateLocal, final LocalDateTime endDateLocal,
final Paging pagingInstruction);
/**
*
* Retrieve an array of {@link StravaSegmentEffort segment efforts}, for a given {@link StravaSegment}.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if the segment does not exist.
*
*
*
* URL GET https://www.strava.com/api/v3/segments/:id/all_efforts
*
*
* @see http://strava.github.io/api/v3/segments/#efforts
*
* @param segmentId
* The id of the {@link StravaSegment} for which {@link StravaSegmentEffort segment efforts} are to be returned
* @param pagingInstruction
* (Optional) paging parameters
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary {@link StravaResourceState representations} sorted by start_date_local ascending or by elapsed_time if an
* athlete_id is provided.
*/
public CompletableFuture> listSegmentEffortsAsync(final Integer segmentId, final Paging pagingInstruction);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete 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
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param athleteId
* Identifier of the {@link StravaAthlete} for which starred {@link StravaSegment segments} are to be returned
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete}.
*/
public List listStarredSegments(final Integer athleteId);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete 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
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param athleteId
* Identifier of the {@link StravaAthlete} for which starred {@link StravaSegment segments} are to be returned
* @param pagingInstruction
* (Optional) paging instructions
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete}.
*/
public List listStarredSegments(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete 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
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param athleteId
* Identifier of the {@link StravaAthlete} for which starred {@link StravaSegment segments} are to be returned
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete}.
*/
public CompletableFuture> listStarredSegmentsAsync(final Integer athleteId);
/**
*
* Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete 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
*
*
* @see http://strava.github.io/api/v3/segments/#starred
*
* @param athleteId
* Identifier of the {@link StravaAthlete} for which starred {@link StravaSegment segments} are to be returned
* @param pagingInstruction
* (Optional) paging instructions
* @return Returns a {@link StravaResourceState#SUMMARY summary representation} of the {@link StravaSegment segments} starred by the identified {@link StravaAthlete}.
*/
public CompletableFuture> listStarredSegmentsAsync(final Integer athleteId, final Paging pagingInstruction);
/**
*
* 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
*
*
* @see http://strava.github.io/api/v3/segments/#explore
*
* @param southwestCorner
* The southwest corner of the area to be explored
* @param northeastCorner
* The northeast corner of the area to be explored
* @param activityType
* (Optional) "running" or "riding", default is riding
* @param minCat
* (Optional) Minimum climb category filter
* @param maxCat
* (Optional) Maximum climb category filter
* @return Returns an array of up to 10 segment objects
*/
public StravaSegmentExplorerResponse segmentExplore(final StravaMapPoint southwestCorner, final StravaMapPoint northeastCorner, final StravaSegmentExplorerActivityType activityType,
final StravaClimbCategory minCat, final 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
*
*
* @see http://strava.github.io/api/v3/segments/#explore
*
* @param southwestCorner
* The southwest corner of the area to be explored
* @param northeastCorner
* The northeast corner of the area to be explored
* @param activityType
* (Optional) "running" or "riding", default is riding
* @param minCat
* (Optional) Minimum climb category filter
* @param maxCat
* (Optional) Maximum climb category filter
* @return Returns an array of up to 10 segment objects
*/
public CompletableFuture segmentExploreAsync(final StravaMapPoint southwestCorner, final StravaMapPoint northeastCorner,
final StravaSegmentExplorerActivityType activityType, final StravaClimbCategory minCat, final StravaClimbCategory maxCat);
/**
*
* Star or unstar a segment
*
*
* @param segmentId
* The id of the segment to be starred
* @param starred
* true if segment is to be starred, false if segment is to be unstarred
* @return Detailed representation of the segment, will be null if the segment does not exist, or will be one with PRIVATE resource state if the segment is flagged as private and
* cannot be accessed
*/
public StravaSegment starSegment(final Integer segmentId, final Boolean starred);
/**
*
* Star or unstar a segment
*
*
* @param segmentId
* The id of the segment to be starred
* @param starred
* true if segment is to be starred, false if segment is to be unstarred
* @return Detailed representation of the segment
*/
public CompletableFuture starSegmentAsync(final Integer segmentId, final Boolean starred);
}