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. The activity might be fully processed even if segment processing is not complete.

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.

There are many attributes defined by FIT. Below is an overview of the ones used by Strava.

MESSAGE TYPES ATTRIBUTES
file_id manufacturer
product
time_created
session sport
sub_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 & session.sub_sport.

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.

A reference TCX file can be obtained for any of your own activities from the Strava website. Visit here, 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 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 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.

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 Device 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.

Device Mapping

Strava maintains a database of devices for display on activities uploaded from them. If you manufacture a device and would like it mapped on Strava, the uploaded files simply need to follow one of the following requirements:

  1. TCX: A unique device name in <Creator>.<Name>UNIQUE_DEVICE_NAME</Name>.</Creator>
  2. FIT: A registered manufacturer & unique product, the manufacturer ID must be assigned to your company by ant+
  3. GPX: A unique device name in <gpx version="1.1" creator="UNIQUE_DEVICE_NAME">

Request a device mapping by submitting this form which requires the following information:

  • A compliant sample file for each type of file you support
  • Exact name of your company
  • Exact name of device
  • URI to device product page
  • Official contact & support info
  • Existence of a barometric altimeter in the device

How to Upload an Activity

Requires activity: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
sport_type: string optional, case sensitive
Possible values : "AlpineSki", "BackcountrySki", "Badminton", "Canoeing", "Crossfit", "EBikeRide", "Elliptical", "EMountainBikeRide", "Golf", "GravelRide", "Handcycle", "HighIntensityIntervalTraining", "Hike", "IceSkate", "InlineSkate", "Kayaking", "Kitesurf", "MountainBikeRide", "NordicSki", "Pickleball", "Pilates", "Racquetball", "Ride", "RockClimbing", "RollerSki", "Rowing", "Run", "Sail", "Skateboard", "Snowboard", "Snowshoe", "Soccer", "Squash", "StairStepper", "StandUpPaddling", "Surfing", "Swim", "TableTennis", "Tennis", "TrailRun", "Velomobile", "VirtualRide", "VirtualRow", "VirtualRun", "Walk", "WeightTraining", "Wheelchair", "Windsurf", "Workout", "Yoga" Overrides sport type detected from file, if left unspecified sport type detected from file will be used
name: string optional
if not provided, will be populated using start date and location, if available
description: string optional
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, case insensitive
the actual activity data, if gzipped the data_type must end with .gz
activity_type: string optional, case insensitive.
Possible values : "AlpineSki", "BackcountrySki", "Canoeing", "Crossfit", "EBikeRide", "Elliptical", "Golf", "GravelRide", "Handcycle", "Hike", "IceSkate", "InlineSkate", "Kayaking", "Kitesurf", "NordicSki", "Ride", "RockClimbing", "RollerSki", "Rowing", "Run", "Sail", "Skateboard", "Snowboard", "Snowshoe", "Soccer", "StairStepper", "StandUpPaddling", "Surfing", "Swim", "Velomobile", "VirtualRide", "VirtualRun", "Walk", "WeightTraining", "Wheelchair", "Windsurf", "Workout", "Yoga" Deprecated: prefer using sport_type, will be ignored if sport_type is included. Overrides type detected from file, if left unspecified type detected from file will be used.
DEFINITION

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

Example Request

For file, the @ symbol means to use the content of the file at the file path we specify. Otherwise, we are just giving it a string that’s the file name, not the content.

$ curl -X POST https://www.strava.com/api/v3/uploads \
    -H "Authorization: Bearer abcd123abcd123abcd123abcd123" \
    -F activity_type="walk" \
    -F name="Test Walk" \
    -F description="Test description" \
    -F trainer=0 \
    -F commute=0 \
    -F data_type="gpx" \
    -F external_id="98765" \
    -F file=@/Users/serenawilliams/Downloads/walk.gpx
Example Response While Processing

The external ID will show after the upload is complete.

    {
      "id": 123456,
      "id_str": "123456",
      "external_id": null,
      "error": null,
      "status": "Your activity is still being processed.",
      "activity_id": null
    }
Example Response When Complete

To see if it is complete, you will have to check the upload status (below).

    {
      "id": 123456,
      "id_str": "123456",
      "external_id": "98765.gpx",
      "error": null,
      "status": "Your activity is ready.",
      "activity_id": 153243126
    }
Returns an Upload Status Object

This object will return a code and an English language status. On success, a 201 Created will be accompanied by a status of success. This indicates that the activity has been successfully accepted, but is still processing. On error, the 400 Bad Request will be accompanied by a status describing the error, potentially containing HTML.

Check Upload Status

A successful upload will return a response 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. The mean processing time is around 8 seconds.

Attributes
id: integer
id_str: string
external_id: string
error: string may be null
if there was an error during processing, this will contain a human readable error message that may include escaped HTML
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.’
activity_id: integer may be null
DEFINITION

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

Example Request
    $ curl -G https://www.strava.com/api/v3/uploads/123456 \
        -H "Authorization: Bearer 83ebeabdec09f6670863766f792ead24d61fe3f9"
Example Response
    {
      "id": 123456,
      "id_str": "123456",
      "external_id": "98765.gpx",
      "error": null,
      "status": "Your activity is ready.",
      "activity_id": 153243126
    }

Errors

You 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 may also include escaped HTML.

Example Error Response
    {
      "id": 123456,
      "id_str": "123456",
      "external_id": null,
      "error": "Test_Walk.gpx duplicate of activity 21234316",
      "status": "There was an error processing your activity.",
      "activity_id": null
    }