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 indicates level of detail. Possible values: 2 -> ‘summary’, 3 -> ‘detail’ |
| 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 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"
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"
}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
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 |
| 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 or absolute local time ascending.
Filtering parameters, like 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
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_19’, ‘20_24’, ‘25_34’, ‘35_44’, ‘45_54’, ‘55_64’, ‘65_69’, ‘70_74’, ‘75_plus’ |
| weight_class: |
string optional pounds ‘0_74’, ‘75_99’, ‘100_124’, ‘125_149’, ‘150_164’, ‘165_179’, ‘180_199’, ‘200_224’, ‘225_249’, ‘250_plus’ or kilograms ‘0_34’, ‘35_44’, ‘45_54’, ‘55_64’, ‘65_74’, ‘75_84’, ‘85_94’, ‘95_104’, ‘105_114’, ‘115_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 W.",
"rank": 0,
"elapsed_time": 360,
"moving_time": 360,
"start_date": "2013-03-29T13:49:35Z",
"start_date_local": "2013-03-29T06:49:35Z"
},
{
"athlete_name": "Chris Z.",
"elapsed_time": 374,
"moving_time": 374,
"start_date": "2012-02-23T14:50:16Z",
"start_date_local": "2012-02-23T06:50:16Z",
"rank": 1
}
]
}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"
}
]
}