strava-v3: Simple Node wrapper for Strava's v3 API

Status

Supports API functionality for all API endpoints from oauth to uploads:

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

Installation

npm install strava-v3

Quick start

• Create an application at strava.com/settings/api and make note of your access_token
• from the root of your node application: $ npm install strava-v3
• $ mkdir data
• $ cp node_modules/strava-v3/strava_config data/strava_config
• Open data/strava_config in your favorite text editor and supply your applications access_token to the access_token field
• Use it!

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

Resources

• Strava Developers Center
• Strava API Reference

Usage

Config and Environment Variables

The template strava_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)"
}

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

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

General

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

var strava = require('strava-v3')
strava.<api endpoint>.<api endpoint option>(args,callback)

Example usage:

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

Overriding the default access_token

You'll probably want to do this with every call once your app is in production, using an access_token specific to a validated user allows for detailed athlete information, as well as the option for additional PUT/POST/DELETE privileges.

Just add the property 'access_token':'your access_token' to the args parameter of your call, the wrapper will use the provided access_token instead of the default in data/strava_config.

Example usage:

var strava = require('strava-v3');
strava.athlete.get({'access_token':'abcde'},function(err,payload,limits) {
    //do something with your payload, track rate limits
});

Dealing with pagination

For those API calls that support pagination, you can control both the page being retrieved and the number of responses to return per_page by adding the corresponding properties to args.

Example usage:

var strava = require('strava-v3');
strava.athlete.listFollowers({
    'page':1
    , 'per_page':2
},function(err,payload,limits) {
    //do something with your payload, track rate limits
});

Uploading files

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

Example usage:

var strava = require('strava-v3');
strava.uploads.post({
    'data_type':'gpx'
    , 'file': 'data/your_file.gpx'
    , 'name': 'Epic times'
    , 'statusCallback': function(err,payload) {
        //do something with your payload
    }
},function(err,payload,limits) {
    //do something with your payload, track rate limits
});

Rate limits

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

Returns null if X-Ratelimit-Limit or X-RateLimit-Usage headers are not provided

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

Supported API Endpoints

Oauth:

• strava.oauth.getRequestAccessURL(args)
• strava.oauth.getToken(code,done)
• strava.oauth.deauthorize(args,done)

Athlete:

• strava.athlete.get(args,done)
• strava.athlete.update(args,done)
• strava.athlete.listFriends(args,done)
• strava.athlete.listFollowers(args,done)
• strava.athlete.listActivities(args,done)
• strava.athlete.listRoutes(args,done)
• strava.athlete.listClubs(args,done)
• strava.athlete.listZones(args,done)

Athletes:

• strava.athletes.get(args,done)
• strava.athletes.listFriends(args,done)
• strava.athletes.listFollowers(args,done)
• strava.athletes.stats(args,done)
• strava.athletes.listKoms(args,done)
• strava.athletes.stats(args,done)

Activities:

• strava.activities.get(args,done)
• strava.activities.create(args,done)
• strava.activities.update(args,done)
• strava.activities.delete(args,done)
• strava.activities.listFriends(args,done)
• 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)
• strava.activities.listRelated(args,done)

Clubs:

• strava.clubs.get(args,done)
• strava.clubs.listMembers(args,done)
• strava.clubs.listActivities(args,done)
• strava.clubs.listAnnouncements(args,done)
• strava.clubs.listEvents(args,done)
• strava.clubs.listAdmins(args,done)
• strava.clubs.joinClub(args,done)
• strava.clubs.leaveClub(args,done)

Gear:

• strava.gear.get(args,done)

Running Races:

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

Routes:

• strava.routes.get(args,done)

Segments:

• strava.segments.get(args,done)
• strava.segments.listStarred(args,done)
• strava.segments.listEfforts(args,done)
• strava.segments.listLeaderboard(args,done)
• strava.segments.explore(args,done)

Segment Efforts:

• strava.segmentEfforts.get(args,done)

Streams:

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

Uploads:

• strava.uploads.post(args,done)

Development

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

Running the tests

You'll first need to supply data/strava_config with an access_token that has both private read and write permissions:

• Make sure you've filled out all the fields in data/strava_config.
• Use strava.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 parameter code will be included in the redirection url.
• Exchange the code for a new access_token:

strava.oauth.getToken(code,function(err,payload,limits) {
    console.log(payload);
});

• You're done! Paste the new access_token to data/strava_config and go run some tests:

yarn test.

How the tests work

Using the provided access_token tests will access each endpoint individually:

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