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 under 2 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.

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.

Activity type is detected from session.sport & session.sub_sport.

In order to provide a registered manufacturer & unique product, the manufacturer ID must be assigned to your company by (ANT+).

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> <DistanceMeters>, and <Calories> from the <Lap> tag. All other aggregated 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 geospatial 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
• cad as cadence

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, unless it is clearly inaccurate. 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 in TCX/GPX files, and manufacturer/product ID values in FIT files. These values 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.

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

Note that in the future the ID will be a 64-bit value, too large to be represented in 32 bits, or as a JavaScript number. Please ensure you can handle 64-bit integers, or use the id_str field.

    {
      "id": 123456,
      "id_str": "123456",
      "external_id": "98765.gpx",
      "error": null,
      "status": "Your activity is still being processed.",
      "activity_id": null
    }

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 under 2 seconds.

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
    }