Module: Strava::Api::Endpoints::Segments

Included in:
Client
Defined in:
lib/strava/api/endpoints/segments.rb

Overview

API endpoints for Strava segments.

Segments are specific sections of road or trail where athletes can compete for time. This module provides methods for exploring, retrieving, and starring segments.

See Also:

Instance Method Summary collapse

Instance Method Details

#explore_segments(options = {}) ⇒ Array<Strava::Models::ExplorerSegment>

Explore segments in a geographic area.

Returns the top 10 segments matching a specified query within a rectangular geographic boundary. Useful for discovering popular segments in an area.

Examples:

Explore segments in an area

segments = client.explore_segments(
  bounds: [40.7,-74.0,40.8,-73.9],
  activity_type: 'running'
)

Parameters:

  • options (Hash) (defaults to: {}) —

    Search parameters

Options Hash (options):

  • :bounds (Array<Float>) —

    Required. Rectangular boundary as [sw_lat, sw_lng, ne_lat, ne_lng]

  • :activity_type (String) —

    Activity type: 'running' or 'riding'

  • :min_cat (Integer) —

    Minimum climbing category (0-5)

  • :max_cat (Integer) —

    Maximum climbing category (0-5)

Returns:

Raises:

  • (ArgumentError)

See Also:



37
38
39
40
41
42
43
44
45
 
# File 'lib/strava/api/endpoints/segments.rb', line 37

def explore_segments(options = {})
  raise ArgumentError, 'Required argument :bounds missing' if options[:bounds].nil?

  bounds = options[:bounds]
  bounds = bounds.map(&:to_s).join(',') if bounds.is_a?(Array)
  get('segments/explore', options.merge(bounds: bounds))['segments'].map do |row|
    Strava::Models::ExplorerSegment.new(row)
  end
end

#segment(id_or_options, options = {}) ⇒ DetailedSegment

Returns the specified segment.

Retrieves detailed information about a specific segment including location, elevation profile, and the athlete's personal records on that segment.

Examples:

Get a segment by ID

segment = client.segment(229781)
puts "#{segment.name}: #{segment.distance_s} with #{segment.average_grade}% grade"

Parameters:

  • id_or_options (String, Integer, Hash) —

    Either a segment ID or a hash of options including :id

  • options (Hash) (defaults to: {}) —

    Additional options (if first parameter is an ID)

Returns:

  • (DetailedSegment) —

    The detailed segment information



85
86
87
88
 
# File 'lib/strava/api/endpoints/segments.rb', line 85

def segment(id_or_options, options = {})
  id, options = parse_args(id_or_options, options)
  Strava::Models::DetailedSegment.new(get("segments/#{id}", options))
end

#star_segment(id_or_options, options = {}) ⇒ DetailedSegment

Stars/Unstars the given segment for the authenticated athlete.

Adds or removes a segment from the athlete's starred/favorite segments. Starred segments appear in the athlete's starred segments list and can be used to track performance over time.

Examples:

Star a segment

segment = client.star_segment(229781, starred: true)

Unstar a segment

segment = client.star_segment(229781, starred: false)

Parameters:

  • id_or_options (String, Integer, Hash) —

    Either a segment ID or a hash of options including :id

  • options (Hash) (defaults to: {}) —

    Additional options (if first parameter is an ID)

Options Hash (options):

  • :starred (Boolean) —

    If true, star the segment; if false, unstar the segment (required)

Returns:

  • (DetailedSegment) —

    The updated segment with new starred status

Raises:

  • (ArgumentError) —

    If :starred option is not provided



111
112
113
114
115
116
 
# File 'lib/strava/api/endpoints/segments.rb', line 111

def star_segment(id_or_options, options = {})
  id, options = parse_args(id_or_options, options)
  raise ArgumentError, 'Required argument :starred missing' if options[:starred].nil?

  Strava::Models::DetailedSegment.new(put("segments/#{id}/starred", options))
end

#starred_segments(options = {}) {|SummarySegment| ... } ⇒ Array<SummarySegment>, Cursor

List of the authenticated athlete's starred segments.

Returns a paginated list of segments that the authenticated athlete has starred. Starred segments are favorites that the athlete wants to track their performance on.

Examples:

List all starred segments

starred = client.starred_segments
starred.each do |segment|
  puts "#{segment.name}: #{segment.distance_s}"
end

Parameters:

  • options (Hash) (defaults to: {}) —

    Pagination options

Options Hash (options):

  • :page (Integer) —

    Page number

  • :per_page (Integer) —

    Number of items per page. Defaults to 30

Yields:

  • (SummarySegment) —

    Yields each segment in the paginated results

Returns:

  • (Array<SummarySegment>, Cursor) —

    Array of starred segments or Cursor for iteration



66
67
68
 
# File 'lib/strava/api/endpoints/segments.rb', line 66

def starred_segments(options = {}, &block)
  paginate 'segments/starred', options, Strava::Models::SummarySegment, &block
end