Uploading to Strava

Uploading to Strava is an asynchronous process. A file is uploaded using a multipart/form-data POST request which performs initial checks on the data and enqueues the file for processing. The activity will not appear in other API requests until it has finished processing successfully.

Processing status may be checked by polling Strava. A one-second or longer polling interval is recommended. The mean processing time is currently around 8 seconds. Once processing is complete, Strava will respond to polling requests with the activity’s ID.

Errors can occur during the submission or processing steps and may be due to malformed activity data or duplicate data submission.

 

Supported file types

Strava supports FIT, TCX and GPX file types as described below. New file types are not on the road map. Developers are encouraged to use one of these types as it will also maximize compatibility with other fitness applications.

All files are required to include a time with each trackpoint or record, as defined by the file format. Information such as lat/lng, elevation, heartrate, etc. is optional. Manual creation of activities without a data file is not currently supported by the API.

If you feel your file is compatible with the standards but is still not uploading to Strava, please verify that it works with other fitness applications before contacting support.

FIT - Flexible and Interoperable Data Transfer

Strava strives to comply with the FIT Activity File (FIT_FILE_TYPE = 4) spec as defined in the official FIT SDK.

Many, many, attributes are defined by FIT. Below is an overview of those used by Strava.

message types attributes
file_id manufacturer
product
time_created
session sport
total_elapsed_time
total_timer_time
total_distance
total_ascent
lap timestamp
total_elapsed_time
total_timer_time
total_distance
total_ascent
record timestamp
position_lat
position_long
altitude
heart_rate
cadence
distance
power
temperature
event timestamp
type

Activity type is detected from session.sport.

Reference File

A reference FIT file can be obtained by recording an activity using any mainstream Garmin device. More information and development tools can be found in the FIT SDK.

TCX - Training Center Database XML

The TCX format was developed by Garmin as part of their Training Center software. For Strava users, an advantage is its ability to include power information. However, it does not support temperature. Strava supports version 2 as defined by Garmin (schema file).

The base version of TCX does not allow for the inclusion of run cadence or power. As a result, TCX has been extended. From the extensions available, Strava extracts from the <Trackpoint> tag:

  • runcadence as cadence
  • watts as power.

Strava reads TCX Courses and only uses the <Track>, <TotalTimeSeconds> and <DistanceMeters> from the <Lap> tag. All other averaging information is ignored.

Activity type is detected from <Activity Sport="*"> where ‘biking’, ‘running’, ‘hiking’, ‘walking’ and ‘swimming’ are mapped to their respective activity types. No other types are currently supported.

Reference File

A reference TCX file can be obtained for any of your own activities from the Strava website. Visit http://www.strava.com/activities/:id/export_tcx first replacing :id with the ID of one of your own activities.

GPX - GPS Exchange Format

GPX is a widely used XML format for geospacial data. Strava follows version 1.1 as defined by Topografix.

The base version of GPX does not allow for the inclusion of heartrate, cadence, distance or temperature data. As a result, extensions to GPX were created and Strava supports the two most popular plus a general format. The extensions extend the <trkpt> tag to include extra attributes with each datapoint.

Garmin’s Track Point Extension v1
From the extensions available, Strava extracts:

  • atemp as temperature
  • hr as heartrate.

Cluetrust GPX extension
From the extensions available, Strava extracts:

  • cadence as cadence
  • distance as distance
  • hr as heartrate
  • temp as temperature.

Strava also detects general tags placed in the <extensions> tag of each <trkpt> tag. Strava extracts:

  • cadence as cadence
  • distance as distance
  • heartrate as heartrate
  • power as power.

Some smaller organizations have created their own undefined extensions to GPX. Adding support for these extensions is not on the roadmap and developers are encouraged to use one of those above as it will also maximize compatibility with other fitness applications.

Reference File

A reference GPX file can be obtained for any of your own activities from the Strava website. Visit http://www.strava.com/activities/:id/export_gpx first replacing :id with the ID of one of your own activities.

 

Device and elevation data

For devices with a barometric altimeter the elevation data is taken as is from the file. Otherwise it is recomputed using the provided lat/lng points and an elevation database. More information.

Device type is detected in all file types from standard ‘creator’ tags. These tags are then matched to a list of known devices. In some cases the name of the device will be displayed along with the activity details on strava.com.

A generic “with barometer” device is provided to force the system to use the elevation data from TCX and GPX file types. One only needs to add “with barometer” to the end of the creator name. For example, a TCX file would include something like:

  <Creator>
    <Name>My Awesome App with barometer</Name>
  </Creator>


and a GPX file should have an updated creator like:

  <gpx version="1.1" creator="Best app ever with Barometer">


For total elevation gain, the value is read directly from FIT file headers if the device includes a barometric altimeter. Otherwise, elevation gain will be computed from the elevation data and may be different than reported on the device. Note that to compute elevation gain noise must be removed from the elevation data and different algorithms/sites will produce different results. More information.

 

Upload an activity

Requires write permissions, as requested during the authorization process.

Posting a file for upload will enqueue it for processing. Initial checks will be done for malformed data and duplicates.

Parameters

activity_type: string optional, case insensitive
possible values: ride, run, swim, workout, hike, walk, nordicski, alpineski, backcountryski, iceskate, inlineskate, kitesurf, rollerski, windsurf, workout, snowboard, snowshoe, ebikeride, virtualride
Type detected from file overrides, uses athlete’s default type if not specified
name: string optional
if not provided, will be populated using start date and location, if available
description: string optional
private: integer optional
set to 1 to mark the resulting activity as private, ‘view_private’ permissions will be necessary to view the activity
If not specified, set according to the athlete’s privacy setting (recommended)
trainer: integer optional
activities without lat/lng info in the file are auto marked as stationary, set to 1 to force
commute: integer optional
set to 1 to mark as commute
data_type: string required case insensitive
possible values: fit, fit.gz, tcx, tcx.gz, gpx, gpx.gz
external_id: string optional
data filename will be used by default but should be a unique identifier
file: multipart/form-data required
the actual activity data, if gzipped the data_type must end with .gz

Returns an Upload Status object

This object will include an English language status. If success, it will indicate the data is still processing. If there was an error, it will describe the error, potentially containing HTML.

Upon a successful submission the request will return 201 Created. If there was an error the request will return 400 Bad Request.

Definition

POST https://www.strava.com/api/v3/uploads

Example request

$ curl -X POST https://www.strava.com/api/v3/uploads \
    -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9" \
    -F activity_type=ride \
    -F file=@test.fit \
    -F data_type=fit

Example response

{
  "id": 16486788,
  "external_id": "test.fit",
  "error": null,
  "status": "Your activity is still being processed.",
  "activity_id": null
}

 

Check upload status

Upon upload, Strava will respond with an upload ID. You may use this ID to poll the status of your upload. Strava recommends polling no more than once a second. Polling more frequently is unnecessary. The mean processing time is around 8 seconds.

Attributes

id: integer
external_id: string
activity_id: integer may be null
status: string
describes the error, possible values: ‘Your activity is still being processed.’, ‘The created activity has been deleted.’, ‘There was an error processing your activity.’, ‘Your activity is ready.’
error: string may be null
if there was an error during processing, this will contain a human a human readable error message that may include escaped HTML

Definition

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

Example request

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

Example responses

{
  "id": 16486788,
  "external_id": "test.fit",
  "error": null,
  "status": "Your activity is ready.",
  "activity_id": 14296970
}

 

{
  "id": 16486769,
  "external_id": "testing.fit",
  "error": null,
  "status": "The created activity has been deleted.",
  "activity_id": null
}

 

Errors

One can determine if there was an error during upload by checking the error attribute for null. At this time error and status messages returned as part of the Upload object are human readable English. They many also include escaped HTML.

Example response

{
  "id": 16486790,
  "external_id": "test.fit",
  "error": "test.fit duplicate of activity 14296882",
  "status": "There was an error processing your activity.",
  "activity_id": null
}