Segments

Segments are specific sections of road. Athletes’ times are compared on these segments and leaderboards are created.

Detailed representation attributes 

id: integer
resource_state: integer
name: string
activity_type: string
‘Ride’ or ‘Run’
distance: float
meters
average_grade: float
percent
maximum_grade: float
percent
elevation_high: float
meters
elevation_low: float
meters
start_latlng: [latitude, longitude]
end_latlng: [latitude, longitude]
climb_category: integer
[0, 5], higher is harder
ie. 5 is Hors catégorie, 0 is uncategorized
city: string
state: string
country: string
private: boolean
starred: boolean
true if authenticated athlete has starred segment
created_at: time string
updated_at: time string
total_elevation_gain: float
meters
map: object
includes a summary polyline
effort_count: integer
number of attempts
athlete_count: integer
number of unique athletes
hazardous: boolean
star_count: integer
number of stars on this segment.


Summary representation attributes 

The summary representation of the segment object is the same as the detailed representation, except it does NOT include these attributes:

    created_at
    updated_at
    total_elevation_gain
    map
    effort_count
    athlete_count
    star_count

Example segment

{
  "id": 229781,
  "resource_state": 3,
  "name": "Hawk Hill",
  "activity_type": "Ride",
  "distance": 2684.82,
  "average_grade": 5.7,
  "maximum_grade": 14.2,
  "elevation_high": 245.3,
  "elevation_low": 92.4,
  "start_latlng": [
    37.8331119,
    -122.4834356
  ],
  "end_latlng": [
    37.8280722,
    -122.4981393
  ],
  "climb_category": 1,
  "city": "San Francisco",
  "state": "CA",
  "country": "United States",
  "private": false,
  "starred": false,
  "created_at": "2008-01-01T17:44:00Z",
  "updated_at": "2013-09-04T20:00:50Z",
  "total_elevation_gain": 155.7,
  "map": {
    "id": "s229781",
    "polyline": "}g|e...VJr@",
    "resource_state": 3
  },
  "effort_count": 51335,
  "athlete_count": 7036,
  "hazardous": false,
  "star_count": 0
}

 

Retrieve a segment

Retrieve details about a specific segment.

Parameters

id: integer required

Returns a detailed representation of the segment.

Definition

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

Example request

$ curl -G https://www.strava.com/api/v3/segments/229781 \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9"

 

List starred segment

Returns a summary representation of the segments starred by the authenticated user. Pagination is supported.

Parameters

page: integer optional
per_page: integer optional

Note: adds in an athlete_pr_effort object if applicable. This represents the PR of the requesting athlete.

Definition

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

Example request

$ curl -G https://www.strava.com/api/v3/segments/starred \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9"

Example segment

{
  "id": 229781,
  "resource_state": 2,
  "name": "Hawk Hill",
  "activity_type": "Ride",
  "distance": 2684.82,
  "average_grade": 5.7,
  "maximum_grade": 14.2,
  "elevation_high": 245.3,
  "elevation_low": 92.4,
  "start_latlng": [
    37.8331119,
    -122.4834356
  ],
  "end_latlng": [
    37.8280722,
    -122.4981393
  ],
  "start_latitude": 37.8331119,
  "start_longitude": -122.4834356,
  "end_latitude": 37.8280722,
  "end_longitude": -122.4981393,
  "climb_category": 1,
  "city": "San Francisco",
  "state": "CA",
  "country": "United States",
  "private": false,
  "starred": true,
  "hazardous": false,
  "pr_time": 550,
  "athlete_pr_effort": {
    "id": 3439333050,
    "elapsed_time": 550,
    "distance": 2713.4,
    "start_date": "2013-01-21T19:05:07Z",
    "start_date_local": "2013-01-21T11:05:07Z",
    "is_kom": false
  },
  "starred_date": "2014-07-24T23:23:24Z"
}

 

Star a segment

Requires write permissions, as requested during the authorization process.

id: integer required
starred: boolean required
set to ‘true’ to star

Returns a detailed representation of the segment.

Definition

PUT https://www.strava.com/api/v3/segments/:id/starred

 

List efforts

Retrieve an array of segment efforts, for a given segment, filtered by athlete and/or a date range. Pagination is supported.

Parameters

id: integer required
athlete_id: integer
start_date_local: datetime
ISO 8601 formatted date time, see Dates for more information
end_date_local: datetime
ISO 8601 formatted date time, see Dates for more information
page: integer optional
per_page: integer optional

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

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.

Definition

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

Example requests

$ curl -G https://www.strava.com/api/v3/segments/229781/all_efforts \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9" \
    -d athlete_id=227615

$ curl -G https://www.strava.com/api/v3/segments/229781/all_efforts \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9" \
    -d start_date_local=2014-01-01T00:00:00Z
    -d end_date_local=2014-01-01T23:59:59Z

 

Segment leaderboards

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.

Parameters

id: integer required
gender: string optional
‘M’ or ‘F’
age_group: string optional
‘0_24’, ‘25_34’, ‘35_44’, ‘45_54’, ‘55_64’, ‘65_plus’
weight_class: string optional
pounds ‘0_124’, ‘125_149’, ‘150_164’, ‘165_179’, ‘180_199’, ‘200_plus’ or kilograms ‘0_54’, ‘55_64’, ‘65_74’, ‘75_84’, ‘85_94’, ‘95_plus’
following: boolean optional
club_id: integer optional
date_range: string optional
‘this_year’, ‘this_month’, ‘this_week’, ‘today’
context_entries: integer optional
default is 2, max of 15
page: integer optional
per_page: integer optional
default is 10

Returns an array of leaderboard entry objects similar to the example response to the right. Note that effort ids should be considered 64-bit integers and effort_count is deprecated, use entry_count instead.

If the requesting athlete has completed this segment, their entry, along with a “context,” will be returned in addition to the entries defined by page and per_page. The context is a default of 2 entries before and after the requesting athlete’s entry. Entries will not be repeated if there is overlap with those requested by the page and per_page parameters.

For example, if the requesting athlete is 15th on a segment, the default result will include the top 10 plus 13-17 (number 15 plus/minus 2).

Definition

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

Example request

$ curl -G \
    https://www.strava.com/api/v3/segments/229781/leaderboard \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9" \
    -d per_page=2

Example response

{
  "entry_count": 7037,
  "entries": [
    {
      "athlete_name": "Jim Whimpey",
      "athlete_id": 123529,
      "athlete_gender": "M",
      "average_hr": 190.5,
      "average_watts": 460.8,
      "distance": 2659.89,
      "elapsed_time": 360,
      "moving_time": 360,
      "start_date": "2013-03-29T13:49:35Z",
      "start_date_local": "2013-03-29T06:49:35Z",
      "activity_id": 46320211,
      "effort_id": 801006623,
      "rank": 1,
      "athlete_profile": "http://pics.com/227615/large.jpg"
    },
    {
      "athlete_name": "Chris Zappala",
      "athlete_id": 11673,
      "athlete_gender": "M",
      "average_hr": null,
      "average_watts": 368.3,
      "distance": 2705.7,
      "elapsed_time": 374,
      "moving_time": 374,
      "start_date": "2012-02-23T14:50:16Z",
      "start_date_local": "2012-02-23T06:50:16Z",
      "activity_id": 4431903,
      "effort_id": 83383918,
      "rank": 2,
      "athlete_profile": "http://pics.com/227615/large.jpg"
    }
  ]
}

 

Segment explorer

This endpoint can be used to find popular segments within a given area.

Parameters

bounds: floats required
comma separated list of bounding box corners
‘sw.lat,sw.lng,ne.lat,ne.lng’
‘south,west,north,east’
activity_type: string optional
‘running’ or ‘riding’, default is riding
min_cat: integer optional
Minimum climb category filter
max_cat: integer optional
Maximum climb category filter

Returns an array of up to 10 segment objects similar to the example response to the right.

Definition

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

Example request

$ curl -G https://www.strava.com/api/v3/segments/explore \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9" \
    -d bounds=37.821362,-122.505373,37.842038,-122.465977 \

Example response

{
  "segments": [
    {
      "id": 229781,
      "name": "Hawk Hill",
      "climb_category": 1,
      "climb_category_desc": "4",
      "avg_grade": 5.7,
      "start_latlng": [
        37.8331119,
        -122.4834356
      ],
      "end_latlng": [
        37.8280722,
        -122.4981393
      ],
      "elev_difference": 152.8,
      "distance": 2684.8,
      "points": "}g|eFnm@n@Op@VJr@"
    },
    {
      "id": 632535,
      "name": "Hawk Hill Upper Conzelman to Summit",
      "climb_category": 0,
      "climb_category_desc": "NC",
      "avg_grade": 8.10913,
      "start_latlng": [
        37.8334451,
        -122.4941994
      ],
      "end_latlng": [
        37.8281297,
        -122.4980005
      ],
      "elev_difference": 67.29200000000003,
      "distance": 829.834,
      "points": "_j|eFvc@p@SbAu@h@Qn@?RTDH"
    }
  ]
}