The Strava V3 API is a publicly available interface allowing developers access to the rich Strava dataset. The interface is stable and currently used by the Strava mobile applications.
All calls to the Strava API require an
access_token defining the athlete and application making the call. Any registered Strava user can obtain an access_token by first creating an application at https://www.strava.com/settings/api.
The API application settings page provides a public access token to get started. See the Authentication page for more information about generating access tokens and the OAuth authorization flow.
Generally speaking, a Strava API application only has access to a user’s data after the user has authorized the application to use it. Segment and segment leaderboard data is available to all applications.
Strava API usage is limited on a per-application basis using both a 15-minute and daily request limit. The default rate limit allows 600 requests every 15 minutes, with up to 30,000 requests per day. This limit allows applications to make 40 requests per minute for about half the day. As an application grows, its rate limit may need to be adjusted. To request an adjustment, email firstname.lastname@example.org with the subject “Rate Limits”.
An application’s 15-minute limit is reset at natural 15-minute intervals corresponding to 0, 15, 30 and 45 minutes after the hour. The daily limit resets at midnight UTC. Requests exceeding the limit will return
403 Forbidden along with a JSON error message. Note that requests violating the short term limit will still count toward the long term limit.
An application’s limits and usage are reported on the API application settings page as well as returned with every API request as part of the HTTP Headers:
two comma-separated values
|15-minute limit, followed by daily limit.|
two comma-separated values
|15-minute usage, followed by daily usage.|
Below is an example request to the Strava API using HTTPie, along with sample response headers for a successful and rate-limited request:
$ http 'https://www.strava.com/api/v3/athlete' \ 'Authorization:Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9'
Example successful response headers
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Date: Tue, 10 Oct 2020 20:11:01 GMT X-Ratelimit-Limit: 600,30000 X-Ratelimit-Usage: 314,27536
Example rate-limited response headers
HTTP/1.1 403 Forbidden Content-Type: application/json; charset=utf-8 Date: Tue, 10 Oct 2020 20:11:05 GMT X-Ratelimit-Limit: 600,30000 X-Ratelimit-Usage: 692,29300
You will need to have a Java runtime installed on your machine to run Swagger. To generate client code, you first need to install Swagger Codegen. On macOS, you may use Homebrew:
$ brew install swagger-codegen maven
To generate code in a given language, run
swagger-codegen generate and pass the following
--input-spec <spec file>: Use
https://developers.strava.com/swagger/swagger.jsonfor Strava’s API
--config <configuration file>: pass the settings or overrides you want the code generator to honor
--lang <language>: the target programming language you seek to generate code for (running
swagger-codegenby itself will print a list of available languages)
--output <output directory>: where to write the resulting files
This example will generate Java code suitable to be packaged in an Android library:
$ swagger-codegen generate -i https://developers.strava.com/swagger/swagger.json -c config/android.json -l java -o generated/java
Depending on the type of request, objects will be returned in meta, summary or detailed representations. The representation of the returned object is indicated by the resource_state attribute.
Resource states, in increasing levels of detail.
Requests that return multiple items will be paginated to 30 items by default. The page parameter can be used to specify further pages or offsets. The per_page may also be used for custom page sizes up to 200. Note that in certain cases, the number of items returned in the response may be lower than the requested page size, even when that page is not the last. If you need to fully go through the full set of results, prefer iterating until an empty page is returned.
Activity, segment and route API requests may include summary polylines of their respective paths. The values are string encodings of the latitude and longitude points using the Google encoded polyline algorithm format.
Dates and times follow the ISO 8601 standard, unless noted. A few examples:
For some resources the
start_date_local attribute is provided as a convenience. It represents the UTC version of the local start time of the event. Displaying this value as UTC will show the correct local start time. The local time zone is also provided for some resources and can be used along with the start_date to achieve this as well.
Where possible, API V3 strives to use appropriate HTTP verbs for each action.
- HEAD can be issued against any resource to get just the HTTP header info
- GET used for retrieving resources
- POST used for creating resources, or performing custom actions
- PUT used for updating or replacing resources
- DELETE used for removing resources