Strava Live Segments
Live Segments Access
Strava Live Segments is an API that allows users to compare their real time effort with Strava segment efforts on their device. To inquire about Strava Live Segments licensing, contact developers -at- strava.com with the subject line “Strava Live Segments Request” and include your API App ID.
In addition to using a licensed device/app, the Strava user must have access to the Strava Live Segments feature of Strava Subscription. To validate whether a user has access, use the getLoggedInAthlete endpoint. The athlete detail returned by this endpoint will have a field, summit, which is a boolean field. If this value is TRUE, the user should be allowed to use Strava Live Segments on the device.
Segment Selection
The segments available for a user to compare with must include segments starred by that user from the getLoggedInAthleteStarredSegments endpoint.
Additionally, the exploreSegments endpoint can be used to suggest nearby segments. Please note that choosing to compare with a nearby/suggested segment should not star that segment for the Strava user.
Live Segment Details Endpoint
After an app has validated that the user has access to Strava Live Segments, the segment effort data for each selected segment must be retrieved. Licensed applications will have access to the live segments endpoint for this purpose:
GET https://www.strava.com/api/v3/live/segments/:id
The id parameter is the id of the segment of interest.
This endpoint returns the details of multiple segment efforts for the requested segment, in a JSON format that is very similar to the structure of FIT SegmentEffort files. The effort times are aligned along the latitude/longitude stream, so that for any given latitude/longitude point in the segment, the elapsed time of each effort is easily compared. See the example JSON response, below.
The efforts returned by this endpoint can include the following:
- King of the Mountain = 5
- Queen of the Mountain = 6
- Personal Record = 7
- Carrot, the effort one place ahead of the requesting athlete on the leaderboard = 9
- Wolf, the effort one place behind the requesting athlete on the leaderboard = 11
- Most recent effort = 12
- Best time in last 5 efforts, unless it is the same as the most recent effort = 13
Note that if a particular effort does not exist or is not relevant to the athlete, it will not be included in the response.
Success Response
Status Code: 200 Ok
JSON Body Fields:
| segment_id | The id of the requested segment |
| efforts | An array describing the efforts included in this live segment response_type |
| points |
Includes an array of values (aligned point values describing the progress of the segment efforts) and fields (string descriptions of the fields included in each point value)
|
Example truncated JSON response with comments:
{
"segmentId": 89759657800,
"efforts": [
{
"type": 12, // the requesting athlete's most recent effort
"time": 1747, // total duration of this effort
"date": "2018-05-25T15:53:22Z"// start date for this effort
},
{
"type": 9, // carrot effort
"time": 818,
"date": "2012-03-14T20:37:31Z",
"name": "John S" // shortened name of the athlete for this effort
},
{
"type": 11, // wolf effort
"time": 554,
"date": "2013-12-31T17:19:42Z",
"name": "Mary M"
},
{
"type": 6, // queen of the mountain effort
"time": 597,
"date": "2018-09-01T16:20:59Z",
"name": "Jane D"
},
{
"type": 7, // the requesting athlete's personal record
"time": 858,
"date": "2018-04-29T19:42:44Z"
}
],
"points": {
"values": [
[
[
37.899325999999995, // latitude for this point
-122.210994 // longitude for this point
],
0, // distance into the segment for this point, in meters
132.8000030517578, // elevation in meters at this point in the segment
[
0, // elapsed time for the first effort (most recent) at this point, in seconds
0, // elapsed time for the second effort (carrot) at this point, in seconds
0, // elapsed time for the third effort (wolf) at this point, in seconds
0, // elapsed time for the fourth effort (qom) at this point, in seconds
0 // elapsed time for the fifth effort (pr) at this point, in seconds
]
],
[
[
37.899331,
-122.211057
],
5.69921875,
133.1999969482422,
[
297,
0,
1,
0,
1
]
],
[
[
37.899419,
-122.21149199999999
],
45.5,
135.8000030517578,
[
484,
7,
10,
5,
11
]
]
],
"fields": [ // list of the fields included in each point value (above)
"latlng", // first field in each point is the lat/lng array
"distance", // second field in each point is the distance in meters
"elevation", // third field in each point is the elevation in meters
"time" // third field for each point is an array of elapsed time in seconds for each returned effort
]
}
}
Error Responses
- Status Code:
401 Unauthorized- Typically indicates that the application is not licensed to access Strava Live Segments. Theerrorsarray in the response body will have more details. - Status Code
402 Payment Required- Indicates the Strava user does not have access to the Strava Live Segments Subscription feature.