Add Activities

post

The Add Activities (POST v1/me/sport/activities) endpoint provides a way to add Activities to a user’s history. The details of an added Activity include: Activity Type, device name, device type, start time, time zone name, and Metric Types defining the Activity. Nike+ calculates and returns derived data such as duration and NikeFuel in the response.

Note: Similar to the List Activities endpoint, the Add Activities endpoint does not return metric detail data (from the metrics array), only the metric summary data of fuel and distance (from the metricSummary object). You can only retrieve metric detail data for one Activity at a time by calling the Activity Detail endpoint. The Add Activities endpoint also does not return GPS data. You can only retrieve GPS data for one Activity at a time by calling the GPS Data endpoint.

Note: Since Add Activities is a POST method for the v1/me/sport/activities endpoint, the test console is not available.

ACTIVITY TYPES

Activity Types classify the kind of activity a user performs. Different movement patterns, for example, running, cycling, or walking, correspond to different Activity Types. There are now a total of 84 Activity Types available. Developers can offer users the ability to select Activity Types ranging from Badminton to Yoga. With so many Activity Types to choose from, it’s now much easier for users to find an Activity Type that best matches their activity. Nike+ uses the Activity Type to help determine which NikeFuel algorithm to use. These 84 Activity Types provide Nike+ with the opportunity to track many more types of movement, apply the appropriate algorithm, and return a more accurate NikeFuel.

IMPORTANCE OF ACTIVITY TYPE AND METRIC TYPE CLASSIFICATION

The algorithms Nike+ uses to calculate NikeFuel are constantly evolving and expanding. Nike+ uses Activity Types to match an activity with the proper algorithm to calculate NikeFuel. Because Activity Types are so central to calculating NikeFuel, it’s important for developers to make as many Activity Types available to users as possible. When users select an appropriate Activity Type for the activity they are performing, Nike+ can provide a more accurate NikeFuel and ensure a better experience for the user.

But selecting the correct Activity Type is just the beginning. Every Activity Type has one or more Metric Types that must accompany it when a user submits an Activity to Nike+. When the proper Activity Type is accompanied by rich metric data, Nike+ can provide far more meaningful NikeFuel and offer more ways for users to monitor their activities and improve their performance.

METRIC TYPES AND DEVICE LIMITATIONS

The more Metric Types you provide to Nike+, the more accurate your NikeFuel will be and the more enhanced the experience the consumer can have. However, there are a number of legacy devices that Nike+ supports that cannot submit all of the Metric Types currently available. See the METRIC TYPES FOR LEGACY DEVICES table for more information.

METRIC TYPE OPTIONS

The following table shows the relationship between Activity Types and the required Metric Types that must accompany each Activity Type. Each option consists of the minimum required Metric Type or combination of Metric Types for a particular Activity Type. If you submit an Activity Type to Nike+, you must use a minimum of one of the options of Metric Types listed for that Activity Type in the table below. For example, the CYCLE Activity Type has four options and a user must select at least one of these four options when selecting Metric Types.


Users will receive an error if they submit an Activity Type without Metric Types from a corresponding option. For example, if you submit the CYCLE Activity Type with only the speed Metric Type, you will receive an error because this combination is not one of the four options for the CYCLE Activity Type (e.g., speed is in Option 4, but speed must be accompanied by grade and distance for Option 4 to be valid).


Note: These options are only the minimum requirement. Ideally, you should submit as many Metric Types as possible. While a RUN Activity Type, for example, can be associated with only the speed and distance Metric Types (Option 3 below) and return NikeFuel, you can increase the accuracy of NikeFuel and enhance the user’s experience if, for example, you submit heartrate along with GPS information that provides the grade Metric Type. See METRIC TYPES: MORE IS BETTER for more information.

Activity Type Option 1
Option 2
Option 3
Option 4
CYCLE
Distance + Watts + Calories + Weight*
Distance + Watts Distance + Grade + Speed + Heartrate + Age* Distance + Grade + Speed
RUN, WALK Distance + Speed + Calories + Weight* Distance + Speed + Heartrate + Age* Distance + Speed
81 Additional Activity Types: e.g., BASEBALL, BASKETBALL, FOOTBALL, GOLF, SKATEBOARD, SOCCER, TENNIS, TRAINING, OTHER
Calories + Weight* Heartrate + Age*

* Users add the Age and Weight Metric Types in their Nike+ Profile.

USING THE “OTHER” ACTIVITY TYPE

To get the most accurate NikeFuel, it is important to use the appropriate Activity Type and the required and optional Metric Types for that Activity Type. There is, however, an undefined Activity Type, the OTHER Activity Type, that you can use if none of the defined Activity Types match a user’s activity. Because NikeFuel is more accurate when calculated from a defined Activity Type (e.g., RUN, WALK, CYCLE, etc.), you should only use the OTHER Activity Type if none of the defined Activity Types match the user’s activity.

HOW GET AND POST METHODS HANDLE METRIC TYPES

Most Metric Type data is available for each interval of an Activity. Some Metric Types (e.g., distance, fuel, calories) are available in both interval and summary format. And one Metric Type, duration, is only available in summary format. See the INTERVAL AND SUMMARY METRIC TYPES table for more information.

The GET sport/activities/{activityId} method retrieves available summary data of Metric Types along with a listing of the interval data for available Metric Types.

The POST /me/sport/activities method sends interval data in the request and returns summary data in the response (e.g., total distance traveled and total NikeFuel).

See EXAMPLES OF GET AND POST METHODS WITH METRIC TYPES for more information.

Request

POSThttps://api.nike.com/v1/me/sport/activities

QUERY PARAMETERS

Name Type Required Description
access_token String Yes User's access token

REQUEST BODY JSON SCHEMA

REQUEST BODY FIELDS

Note: Although the Add Activities (POST v1/me/sport/activities) endpoint accepts multiple Activities at once, the recommendation is to send only one Activity at a time.
Name Type Required Description
activityType
String
Yes
Type of Activity performed (see Activity Types for full list)
deviceName
String
No
Name of the device (or application name if using an app) that recorded the Activity
deviceType
String
Yes
Type of device that recorded the Activity, e.g., BIKE, ELLIPTICAL, TREADMILL, etc.
startTime
Integer
Yes
Start time of Activity (milliseconds since epoch)
duration Integer No Duration of Activity in milliseconds
timeZoneName String
Yes

Time zone name (see list of tz database time zones) in which the Activity occurred. Nike+ supports political time zones found in the IANA Time Zone Database (e.g., “America/Los_Angeles”). Note:  Nike+ also supports Etc/GMT offset (e.g., “Etc/GMT-8” is the equivalent of “America/Los_Angeles”), but political time zones found in the IANA Time Zone Database are preferable.

metrics
Object
Yes
Metrics object contains metric data (e.g., interval unit, interval value, and Metric Types) and the array (metrics.data) of metric values.
metrics.intervalUnit String Yes Unit of the metric's interval value (metrics.intervalValue); currently, the only allowed unit is "sec" for seconds.
metrics.intervalValue Integer Yes Interval in which to sample the metric values. This value must be “10” for the RUN Activity Type and may be either “5” or “10” for all other Activity Types.
metrics[n].metricTypes Array of Strings Yes List of Metric Types
that are expected for each metric dataset in the metrics[n].data array.
 
See METRIC TYPE OPTIONS for more information on the Metric Types required for a specific Activity Type.
 
Note:  At this time, the user cannot submit the stars Metric Type.
metrics[n].data Array of Array of Numbers Yes

Each subarray corresponds to a data point in the user’s activity.
The order of the data points must be from start to finish.

The elements in each data point must be in the same order as the Metric Types in the metricTypes array.

The first data point must have occurred at the specified startTime. Each data point thereafter must be uniformly distributed according to the intervalValue. For example, if you specify an intervalUnit of “sec” and an intervalValue of “5” for an Activity that lasts 20 seconds, you will need to send data points at 0, 5, 10 and 15 seconds.

Any distance metrics sent must be cumulative since the beginning of the Activity.

SAMPLE REQUEST HEADER

Below is an example of information the HTTP header should have for a POST to the Add Activities (v1/me/sport/activities) endpoint.
POST 
/v1/me/sport/activities?access_token={access token} 
HTTP/1.1
Host: api.nike.com
Content-Type: application/json
Cache-Control: no-cache

SAMPLE REQUEST BODY

[
	{
  	"activityType" : "CYCLE",
  	"deviceName" : "MyApp",
  	"deviceType" : "BIKE",
  	"metrics" :
    	{ "data" : [
         	[ 55.8577630, -3.1921560, 0.0, 0.0035397, 0.1, 3.1666667, 10 ],
         	[ 55.8576650, -3.1920980, 0.0, 0.0186985, 0.9, 1.9313725, 10 ],
         	[ 55.8575770, -3.1920680, 0.0, 0.0315418, 1.1, 2.0196078, 16 ],
         	[ 55.8576970, -3.1919140, 0.0, 0.0485687, 1.3, 2.2843137, 18 ]
      	],
      	"intervalUnit" : "sec",
      	"intervalValue" : 10,
     	 "metricTypes" : [
         	"latitude",
         	"longitude",
         	"elevation",
         	"distance",
         	"grade",
         	"speed",
         	"calories"
      	]
    	},
  	"startTime" : 1406747471000,
        "duration" : 38172,
  	"timeZoneName" : "America/Los_Angeles"
	}
 ] 

Response

RESPONSE BODY JSON SCHEMA

RESPONSE BODY FIELDS

Note: Distances and weights are returned in metric units.
Name Type Description  
activityId String
Activity’s unique identifier  
activityType
String
Activity Type performed, e.g., RUN, WALK, CYCLE, etc.  
deviceName
String
Name of the device (or application name if using an app) that recorded the Activity  
deviceType
String
Type of device that recorded the Activity, e.g., BIKE, ELLIPTICAL, TREADMILL, etc.  
startTime
Integer
Start time of Activity (milliseconds since epoch)  
duration
Integer Duration of Activity in milliseconds  
timeZoneName
String
Time zone name in which the Activity occurred (format time zones according to IANA Time Zone Database, e.g., “America/Los_Angeles” is acceptable, “PST” is not).  
metricSummary Object
Object containing summary metric data for the Activity. Currently only NikeFuel (derived by Nike+) and distance (if submitted) are returned.  
metricSummary.fuel String Amount of NikeFuel gained during the Activity  
metricSummary.distance String Distance user traveled during the Activity in kilometers  

SAMPLE RESPONSE BODY

[
	{
        "links": [
            {
                "rel": "self",
                "href": "https://api.nike.com/v1/me/sport/activities/7434000000020208749690027156366237186906"
            },
            {
                "rel": "gps",
                "href": "https://api.nike.com/v1/me/sport/activities/7434000000020208749690027156366237186906/gps"
            }
        ],
        "activityId": "7434000000020208749690027156366237186906",
        "activityType": "CYCLE",
        "deviceName": "MyApp",
        "deviceType": "BIKE",
        "startTime": 1406747471000,
        "duration" : 38172,
        "timeZoneName": "America/Los_Angeles",
        "metricSummary": {
            "fuel": "151",
            "distance": "0.0485687"
        }
    }
]

METRIC TYPES: MORE IS BETTER

In general, you should submit any Metric Types to Nike+ that your device can provide. Nike+ uses algorithms that link movement patterns and conditions to known energy requirements. These algorithms are continuously evolving to incorporate all of the data collected. When users select the appropriate Activity Type and send as much of the available metric information to Nike+ as possible, they increase the accuracy of their NikeFuel and the potential for feedback about their activity.

For example, you could submit a RUN Activity Type with the Metric Types of speed and distance. The request to the Add Activities (POST v1/me/sport/activities) endpoint might look like this:

[
   {
      "activityType" : "RUN",
      "deviceName" : "Nike Running",
      "deviceType" : "WATCH",
      "metrics" : {
         "data" : [
            [ 0.0035397, 3.1666667],
            [ 0.0186985, 1.9313725],
            [ 0.0315418, 2.0196078],
            [ 0.0485687, 2.2843137]
         ],
         "intervalUnit" : "sec",
         "intervalValue" : 10,
         "metricTypes" : [
            "distance",
            "speed"
         ]
      },
      "startTime" : 1406747471000,
      "duration" : 38172,
      "timeZoneName" : "America/Los_Angeles"
   }
]
But compare this to the same app or device that submits many more Metric Types to Nike+. Along with the distance and speed Metric Types, it sends the latitude, longitude, elevation, grade, calories, gpssignalstrength, and heartrate Metric Types:
[
   {
      "activityType" : "RUN",
      "deviceName" : "Nike Running",
      "deviceType" : "WATCH",
      "metrics" : {
         "data" : [
            [ 55.8577630, -3.1921560, 0.0, 0.0035397, 0.1, 3.1666667, 10, 10, 105 ],
            [ 55.8576650, -3.1920980, 0.0, 0.0186985, 0.9, 1.9313725, 10, 10, 106 ],
            [ 55.8575770, -3.1920680, 0.0, 0.0315418, 1.1, 2.0196078, 16, 10, 105 ],
            [ 55.8576970, -3.1919140, 0.0, 0.0485687, 1.3, 2.2843137, 18, 10, 104 ]
         ],
         "intervalUnit" : "sec",
         "intervalValue" : 10,
         "metricTypes" : [
            "latitude",
            "longitude",
            "elevation",
            "distance",
     	    "grade",
            "speed",
            "calories",
 		"gpssignalstrength"
		"heartrate"
         ]
      },
      "startTime" : 1406747471000,
      "duration" : 38172,
      "timeZoneName" : "America/Los_Angeles"
   }
]

This provides Nike+ with much more data to derive the user’s NikeFuel. Additionally, this Metric Type data is available to enhance the user’s experience in various ways.

For example, users can log in to their Nike+ accounts and display a map of their run that includes NikeFuel, calories, average pace, duration, and average heart rate. Or they can generate a NikeFuel Curve of their run.

And of course, developers can provide apps and devices that use these additional Metric Types to generate maps, Performance Curves, and other information to make it easy for users to see trends across activities, over time, and in comparison to others.

ERROR CODES

Error Code Message
160
Start Time must represent a valid timestamp in the past and after May 23, 2006
170 Invalid or missing Activity Type
180
Invalid or missing Time Zone name
190
The metrics object is missing
200
Do not pass in Activity ID - it will be calculated automatically
210
Do not pass in Metric Summary - it will be calculated automatically
220
Invalid Device Type
230 Missing required Metric Types
240
Invalid Interval Unit
250 Invalid Interval Value
260
Metric data must match metric types
270 Metric data cannot be empty
360 Fuel metrics passed in must be non-negative integers only
For the complete list of error codes, refer to Error Codes and Responses.