Repository files navigation

Supports many but not all Strava API endpoints:

• oauth
• athlete
• athletes
• activities
• clubs
• gear
• running_races
• routes
• segments
• segment_efforts
• streams
• uploads

npm install strava-v3

Importing only the library:

import strava from 'strava-v3';

Importing both the library as well as interfaces:

import { default as strava, Strava } from 'strava-v3';

• Create an application atstrava.com/settings/api and make note of youraccess_token

conststrava=require('strava-v3')strava.config({...})constpayload=awaitstrava.athlete.get({})console.log(payload)

conststrava=require('strava-v3');strava.athlete.get({},function(err,payload,limits){if(!err){console.log(payload);}else{console.log(err);}});

If you are writing an app that other Strava users will authorize against theirown account, you'll need to use the OAuth flow. This requires that you provideaclient_id,client_secret andredirect_uri that ultimately result ingetting back anaccess_token which can be used for calls on behalf of thatuser.

You have three options to configure your OAuth calls:

Use explicit configuration, which will override both the config file and the environment variables:

varstrava=require('strava-v3')strava.config({"access_token"  :"Your apps access token (Required for Quickstart)","client_id"     :"Your apps Client ID (Required for oauth)","client_secret" :"Your apps Client Secret (Required for oauth)","redirect_uri"  :"Your apps Authorization Redirection URI (Required for oauth)",});

You may alternatively supply the values via environment variables named following the conventionSTRAVA_<keyName>, so

• STRAVA_ACCESS_TOKEN =access_token
• STRAVA_CLIENT_ID =client_id
• STRAVA_CLIENT_SECRET =client_secret
• STRAVA_REDIRECT_URI =redirect_uri

The templatestrava_config file can be found at the modules root directory and has the following structure

{"access_token"  :"Your apps access token (Required for Quickstart)","client_id"     :"Your apps Client ID (Required for oauth)","client_secret" :"Your apps Client Secret (Required for oauth)","redirect_uri"  :"Your apps Authorization Redirection URI (Required for oauth)",}

API access is designed to be as closely similar in layout as possible to Strava's own architecture, with the general call definition being

varstrava=require('strava-v3')// Promise APIstrava.<apiendpoint>.<apiendpointoption>(args)// Callback APIstrava.<apiendpoint>.<apiendpointoption>(args,callback)

Example usage:

varstrava=require('strava-v3');strava.athletes.get({id:12345},function(err,payload,limits){//do something with your payload, track rate limits});

You'll may want to use OAuthaccess_tokens on behalf of specific users onceyour app is in production. Using anaccess_token specific to a validated userallows for detailed athlete information, as well as the option for additionalPUT/POST/DELETE privileges.

Use app-specific logic to retrieve theaccess\_token for a particular user, then create a Strava client for that user, with their token:

conststravaApi=require('strava-v3');// ... get access_token from somewherestrava=newstravaApi.client(access_token);constpayload=awaitstrava.athlete.get({})

Less conveniently, you can also explictly pass anaccess_token to API calls:

Example usage:

conststrava=require('strava-v3');constpayload=awaitstrava.athlete.get({'access_token':'abcde'})

For those API calls that support pagination, you can control both thepage being retrieved and the number of responses to returnper_page by adding the corresponding properties toargs.

Example usage:

conststrava=require('strava-v3');constpayload=awaitstrava.athlete.listFollowers({page:1,per_page:2});

To upload a file you'll have to pass in thedata_type as specified in Strava's API reference as well as a stringfile designating the<filepath>/<filename>. If you want to get updates on the status of your upload pass instatusCallback along with the rest of yourargs - the wrapper will check on the upload once a second until complete.

Example usage:

conststrava=require('strava-v3');constpayload=awaitstrava.uploads.post({data_type:'gpx',file:'data/your_file.gpx',name:'Epic times',statusCallback:(err,payload)=>{//do something with your payload}});

According to Strava's API each response contains information about rate limits.For more details see:Rate Limits

Returnsnull ifX-Ratelimit-Limit orX-RateLimit-Usage headers are not provided

In our promise API, only the response body "payload" value is returned as aBluebird promise. To trackrate limiting we use a global counter accessible throughstrava.rateLimiting.The rate limiting status is updated with each request.

// returns true if the most recent request exceeded the rate limitstrava.rateLimiting.exceeded()// returns the current decimal fraction (from 0 to 1) of rate used. The greater of the short and long term limits.strava.rateLimiting.fractionReached();

conststrava=require('strava-v3');strava.athlete.get({'access_token':'abcde'},function(err,payload,limits){//do something with your payload, track rate limitsconsole.log(limits);/*    output:    {       shortTermUsage: 3,       shortTermLimit: 600,       longTermUsage: 12,       longTermLimit: 30000    }    */});

To used the Promise-based API, do not provide a callback. A promise will be returned.

See Strava API docs for returned data structures.

• strava.oauth.getRequestAccessURL(args)
• strava.oauth.getToken(code,done) (Used to token exchange)
• strava.oauth.refreshToken(code) (Callback API not supported)
• strava.oauth.deauthorize(args,done)

• strava.athlete.get(args,done)
• strava.athlete.update(args,done) // only 'weight' can be updated.
• strava.athlete.listActivities(args,done)Get list of activity summaries
• strava.athlete.listRoutes(args,done)
• strava.athlete.listClubs(args,done)
• strava.athlete.listZones(args,done)

• strava.athletes.get(args,done)Get a single activity. args.id is required
• strava.athletes.stats(args,done)

• strava.activities.get(args,done)
• strava.activities.create(args,done)
• strava.activities.update(args,done)
• strava.activities.listFriends(args,done) -> deprecated at 2.2.0
• strava.activities.listZones(args,done)
• strava.activities.listLaps(args,done)
• strava.activities.listComments(args,done)
• strava.activities.listKudos(args,done)
• strava.activities.listPhotos(args,done) -> deprecated at 2.2.0

• strava.clubs.get(args,done)
• strava.clubs.listMembers(args,done)
• strava.clubs.listActivities(args,done)
• strava.clubs.listAdmins(args,done)

• strava.gear.get(args,done)

These methods Authenticate with a Client ID and Client Secret. Since they don'tuse OAuth, they are not available on theclient object.

• strava.pushSubscriptions.list({},done)
• strava.pushSubscriptions.create({callback_url:...},done)
• We set 'object_type to "activity" and "aspect_type" to "create" for you.
• strava.pushSubscriptions.delete({id:...},done)

• strava.runningRaces.get(args,done)
• strava.runningRaces.listRaces(args,done)

• strava.routes.getFile({ id: routeId, file_type: 'gpx' },done)file_type may also be 'tcx'
• strava.routes.get(args,done)

• strava.segments.get(args,done)
• strava.segments.listStarred(args,done)
• strava.segments.listEfforts(args,done)
• strava.segments.explore(args,done)Expects argbounds as a comma separated string, for two points describing a rectangular boundary for the search:"southwest corner latitutde, southwest corner longitude, northeast corner latitude, northeast corner longitude".

• strava.segmentEfforts.get(args,done)

• strava.streams.activity(args,done)
• strava.streams.effort(args,done)
• strava.streams.segment(args,done)

• strava.uploads.post(args,done)

Except for the OAuth calls, errors returned will be instances ofStatusCodeError when the HTTP status code is not 2xx. In the Promise-based API, the promise will be rejected. An error of typeRequestError will be returned if the request fails for technical reasons.

The updated version now uses Axios for HTTP requests and custom error classes for compatibility with the previous implementation.

In the Promise-based API, errors will reject the Promise. In the callback-based API (where supported), errors will pass to theerr argument in the callback.

The project no longer relies on Bluebird. Where applicable, callback handling has been removed.

Example error checking:

const{ StatusCodeError, RequestError}=require('./axiosUtility');// Catch a non-2xx response with the Promise APIbadClient.athlete.get({}).catch(StatusCodeError,function(e){});badClient.athlete.get({},function(err,payload){// err will be an instance of StatusCodeError or RequestError});

TheStatusCodeError object includes extra properties to help with debugging:

• name is alwaysStatusCodeError
• statusCode contains the HTTP status code
• message contains the response's status message and additional error details
• data contains the body of the response, which can be useful for debugging
• options contains the options used in the request
• response contains the response object

TheRequestError object is used for errors that occur due to technical issues, such as no response being received or request setup issues, and includes the following properties:

• name is alwaysRequestError
• message contains the error message
• options contains the options used in the request

This update maintains feature parity with the previous implementation ofrequest-promise while using the Axios HTTP client under the hood.

This package includes a full test suite runnable viayarn test.It will both lint and run shallow tests on API endpoints.

You'll first need to supplydata/strava_config with anaccess_token thathas both private read and write permissions. Look in./scripts for a toolto help generate this token. Going forward we plan to more testing with a mockedversion of the Strava API so testing with real account credentials are not required.

• Make sure you've filled out all the fields indata/strava_config.
• Usestrava.oauth.getRequestAccessURL({scope:"view_private,write"}) to generate the request url and query it via your browser.
• Strava will prompt you (the user) to allow access, say yes and you'll be sent to your Authorization Redirection URI - the parametercode will be included in the redirection url.
• Exchange thecode for a newaccess_token:

// access_token is at payload.access_tokenconstpayload=awaitstrava.oauth.getToken(authorizationCode)

Finally, the test suite has some expectations about the Strava account that itconnects for the tests to pass. The following should be true about the Stravadata in the account:

• Must have at least one activity posted on Strava
• Must have joined at least one club
• Must have added at least one piece of gear (bike or shoes)
• Must have created at least one route
• Most recent activity with an achievement should also contain a segment

(Contributions to make the test suite more self-contained and robust by converting more teststo usenock are welcome!)

• You're done! Paste the newaccess_token todata/strava_config and go run some tests:

yarn test.

Using the providedaccess_token tests will access each endpoint individually:

• (For allGET endpoints) checks to ensure the correct type has been returned from the Strava.
• (ForPUT inathlete.update) changes some athlete properties, then changes them back.
• (ForPOST/PUT/DELETE inactivities.create/update/delete) first creates an activity, runs some operations on it, then deletes it.

You can enable a debug mode for the underlyingrequest module to see detailsabout the raw HTTP requests and responses being sent back and forth from theStrava API.

To enable this, set this in the environment before this module is loaded:

NODE_DEBUG=request

You can also set `process.env.NODE_DEBUG='request' in your script before this module is loaded.

• Strava Developers Center
• Strava API Reference

Authored by Austin Brownaustin@unboundev.com (http://austinjamesbrown.com/).

Currently Maintained by Mark Stosbergmark@rideamigos.com