API for Developers

Overview

The ShareMyFitness API provides you with an unified access to all the fitness data of your group members. Making life easier for you, by giving you:

1. Instant access to all the fitness data of all your group members.
2. Digested and unified single format for all the data, regardless of the device origin.
3. Designed for simplicity, using authentication with JWT and JSON responses.
4. Integrate once with us, and we handle the complexity and changes from all the fitness data providers.
5. Simple response formats, designed to be scalable as new data types are added, without affecting existing integrations.
6. We are constantly adding new fitness data providers, as they come to the market.

The following lines explain how, once you have the right ShareMyFitness account, you can access our REST API.
The process requires you to use your account user and password, to:

1. Get a JWT, which lasts for 3600 seconds
2. Use the JWT in the header of all your calls to available endpoints.
3. GET and DELETE endpoints parameters are passed as Path Parameters, and indicated between the sign #. For example: #membership_id#.
4. By default ALL responses will include:
   1. Code: Identifier of the response
   2. Message: description of the response
   3. Data: Include the HTTP status result for the call, to make it available in the json response, and the actual resulting data. The latter will be explained for each endpoint below.

All possible error responses will be explained at the end.

Get Token

Endpoint

POST /api/v1.0/token

Description

Evaluates the provided user and password, to provided a Json Web Token that will enable access to other endpoints, if the given credentials are valid.
Invalid credentials will generate an error response.

Parameters

parameter	type	optional	description
user	string	no	The sharemyfitness.com user with API access
password	string	no	The password for the given user

Response

A collection with all the Memberships associated to the user. For each membership:

field	type	optional	description
access_token	string	no	Json Web Token (JWT), to be used as the Authentication token for all other endpoints.
token_type	string	no	Always is “Bearer”.
expires_in	integer	no	Number of seconds the token is valid for.

Example

Request (URLEncoded)

POST /api/v1.0/token HTTP/1.1
Host: sharemyfitness.com
Content-Type: application/x-www-form-urlencoded
cache-control: no-cache
user=ale@example.com&password=Sef4%c13e$

Response (HTTP status: 200)

{
	"code": "smf_bearer_token",
	"message": "Here is your Bearer Access Token, to expire in the specified number of seconds",
	"data": {
		"status": 200,
		"token_data": {
			"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTQ3MjY0MH0=.MzNlMGZlZTI5MTEzZmY2MjFjMDljNWY4ZGYzM2Y5M2VmNjEzYmRkMjhiN2FlMDQ5NWRlNDllMjczNjk5NjU0Nw==",
			"token_type": "Bearer",
			"expires_in": 3600
			}
		}
}

Validate Token

Endpoint

POST /api/v1.0/token/validate

Description

Validates if the provided token, passed in the headers, is valid.

Parameters

No parameters are required. The header includes the Authentication Bearer token.

Response

A collection with all the Memberships associated to the user. For each membership it contains:

field	type	optional	description
status	integer	no	Status 200, indicating the token is valid. Any other status refers to an invalid token.

Example

Request (URLEncoded)

POST /api/v1.0/token/validate HTTP/1.1
Host: sharemyfitness.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTUzNTI4Mn0=.ZDViMGI3MTA0OWQ1N2NiMjFiOWVhMTI1YjczOGI5ZTY2ODczODI1OTdjYTU0YzVjMWMwYWFjN2UyYzc3NGQ2MQ==

Response (HTTP status: 200)

{
  "code": "smf_valid_token",
  "message": "Token still valid",
  "data": {
    "status": 200
  }
}

Memberships

Endpoint

GET/api/v1.0/memberships

Description

Returns the details of the valid and active memberships which belong to the authenticated account.

Parameters

No parameters are required. The header includes the Authentication Bearer token.

Response

A collection of the Memberships associated to the user. Each membership includes:

field	type	optional	description
membership_id	integer	no	ID for the given membership
name	string	no	Name of the membership type
number-of-users	integer	no	Number of users the that can register under the membership
registered-users	integer	no	Number of users currently registered under the membership
free-places	integer	no	Number of users still can register under the membership
registration-link	string	no	The registration link to register users under the membership, and access their fitness data later
time-created	timestamp	no	Unix Epoch time when the membership was created

Example

Request (URLEncoded)

GET /api/v1.0/memberships HTTP/1.1
Host: sharemyfitness.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTUzNzcwOH0=.ZjdhNjg0NTExYWIxYmU2MGE2ZWFmODA1ZTU0NzM1ODI5MWU0YmE0Mzk5ZGVlM2IxYTk2Y2Y1NjA1NDI0YjJhYQ==
cache-control: no-cache

Response (HTTP status: 200)

{
  "code": "smf_memberships",
  "message": "All your memberships, in any state",
  "data": {
    "status": 200,
    "memberships": [
      {
        "membership_id": “1840”,
        "name": "Professional",
        "number-of-users": "20",
        "registered-users": "13",
        "free-places": “7”,
        "registration-link": "https://sharemyfitness.com/my-account/?mainAcc=451f61a4a54aabc7ba5d3214de34b98639776d355c165c4352f3a00602ea86d7",
        "time-created": 1535045015
      }
    ]
  }
}

Users

Endpoint

GET /api/v1.0/memberships/#membership_id#/users

Description

Returns the collection of users that are registered under the given membership.

Parameters

field	type	optional	description
membership_id	integer	no	ID of the membership to get users from.

The header includes the Authentication Bearer token.

Response

A collection of the users registered under the membership. Each user includes:

field	type	optional	description
user_id	integer	no	The user ID.
user_email	string	no	Email of the user.
display_name	string	no	Short name to be displayed in the user account.
status	integer	no	Status of the required tracking device for the user: 0: Does not have a linked device. 1: Has a working linked device. 2: Has a linked device, that needs be re-linked to make it work.
last_date	Date	no	The last day of activity data for this user. Format: YYYY-MM-DD

Example

Request (URLEncoded)

GET /api/v1.0/memberships/1840/users HTTP/1.1
Host: sharemyfitness.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTUzNzcwOH0=.ZjdhNjg0NTExYWIxYmU2MGE2ZWFmODA1ZTU0NzM1ODI5MWU0YmE0Mzk5ZGVlM2IxYTk2Y2Y1NjA1NDI0YjJhYQ==
cache-control: no-cache

Response (HTTP status: 200)

{
  "code": "smf_users_details",
  "message": "Details for all the users in the given membership",
  "data": {
    "status": 200,
    "users": [
      {
        "user_id": "52",
        "user_email": "jhon@example.com",
        "display_name": "jhonlyon",
        "full_name": "Jhon Lyon",
        "status": "1",
        "last_date": "2018-10-29"
      },
      {
        "user_id": "58",
        "user_email": "carl@example.com",
        "display_name": "carlluis",
        "full_name": "Carl Luis",
        "status": "1",
        "last_date": null
      },
      {
        "user_id": "61",
        "user_email": "bruce@example.com",
        "display_name": "bruce13",
        "full_name": "Bruce Banner ",
        "status": "1",
        "last_date": "2018-10-19"
      }
    ]
  }
}

Users daily data

Endpoint

GET /api/v1.0/memberships/#membership_id#/users/data/#date#

Description

Returns all the aggregated data, for all the users in the specified membership, on the given date.

Parameters

field	type	optional	description
membership_id	integer	no	ID of the membership to get users from.
date	string	no	Specifies the date to get data for. Format: YYYYMMDD

The header includes the Authentication Bearer token.

Response

A collection of the data of the users registered under the membership. Each one includes:

field	type	optional	description
user_id	integer	no	The user ID.
date	string	no	The day of the provided user data.
minutes	integer	no	Number of active minutes on the given day.
metres	integer	no	The total distance, in meters, the user moved.
steps	integer	no	The number of steps taken by the user.
calories	integer	no	The number of calories spent by the users.

Example

Request (URLEncoded)

GET /api/v1.0/memberships/1840/users/data/20181018 HTTP/1.1
Host: sharemyfitness.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTYwNzY3M30=.YTFjN2Y2MTJhMTA1ZGQ5ODk1ZDE5ZjgzMzE4NWRlODQ0MzQ0OTNhNGRlYzdiN2JmNjk3MzFmZWZiMWVlZTZlZQ==
cache-control: no-cache

Response (HTTP status: 200)

{
  "code": "smf_users_data",
  "message": "Activity data for all the users under the given membership during the specified day",
  "data": {
    "status": 200,
    "activity": [
      {
        "user_id": "68",
        "date": "2018-10-18",
        "minutes": "72",
        "metres": "11567",
        "steps": "13020",
        "calories": "3082"
      },
      {
        "user_id": "61",
        "date": "2018-10-18",
        "minutes": "121",
        "metres": "5640",
        "steps": "5500",
        "calories": "1601"
      },
      {
        "user_id": "52",
        "date": "2018-10-18",
        "minutes": "94",
        "metres": "4490",
        "steps": "6478",
        "calories": "2035"
      }
    ]
  }
}

User data

Endpoint

GET /api/v1.0/memberships/#membership_id#/users/#user_id#/data/#date_from#/#date_to#

Description

Returns the aggregated data, for the specified user in the given membership, between the provided dates

Parameters

field	type	optional	description
membership_id	integer	no	ID of the membership the user is registered with.
user_id	integer	no	ID of the user.
date_from	string	no	The date to get data from. Format: YYYYMMDD
date_from	string	no	The date to get data until. Format: YYYYMMDD

The header includes the Authentication Bearer token.

Response

A collection of the data containing each requested day. Each day includes:

field	type	optional	description
date	string	no	The respective day of data set.
minutes	integer	no	Number of active minutes on the given day.
metres	integer	no	The total distance, in meters, the user moved.
steps	integer	no	The number of steps taken by the user.
calories	integer	no	The number of calories spent by the users.

Example

Request (URLEncoded)

GET /api/v1.0/memberships/1840/users/52/data/20181015/20181018 HTTP/1.1
Host: sharemyfitness.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTYwNzY3M30=.YTFjN2Y2MTJhMTA1ZGQ5ODk1ZDE5ZjgzMzE4NWRlODQ0MzQ0OTNhNGRlYzdiN2JmNjk3MzFmZWZiMWVlZTZlZQ==
cache-control: no-cache

Response (HTTP status: 200)

{
  "code": "smf_user_activity",
  "message": "Activity data for the given user during the specified period",
  "data": {
    "status": 200,
    "activity": [
      {
        "date": "2018-10-18",
        "minutes": "94",
        "metres": "4490",
        "calories": "2035",
        "steps": "6478"
      },
      {
        "date": "2018-10-17",
        "minutes": "98",
        "metres": "4955",
        "calories": "2075",
        "steps": "7562"
      },
      {
        "date": "2018-10-16",
        "minutes": "119",
        "metres": "20227",
        "calories": "2021",
        "steps": "5011"
      },
      {
        "date": "2018-10-15",
        "minutes": "80",
        "metres": "1457",
        "calories": "1891",
        "steps": "4143"
      }
    ]
  }
}

Request User Backfilling

Endpoint

POST /api/v1.0/memberships/#membership_id#/users/#user_id#/backfilling

Description

Generates a request for a new user data backfilling. Once the backfilling request has been fulfilled, it will be notified
back to the client as per the “Notification Settings” under of the “Service Details” in the client account. Those settings
may include notification by email or by posting the notification to a provided URL.

A backfilling will generate up to 60 days of data for the given user, depending on the amount of data available with his data provider.

Parameters

field	type	optional	description
user_id	integer	no	ID of the user to request backfilling for.

The header includes the Authentication Bearer token.

Response

Status code 200, indicating the request has been placed.

field	type	optional	description
status	integer	no	Status 200, indicating the request is placed. Any other status refers to an invalid token

Example

Request (URLEncoded)

GET /api/v1.0/memberships/1840/users/52/backfilling HTTP/1.1
Host: sharemyfitness.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTYwNzY3M30=.YTFjN2Y2MTJhMTA1ZGQ5ODk1ZDE5ZjgzMzE4NWRlODQ0MzQ0OTNhNGRlYzdiN2JmNjk3MzFmZWZiMWVlZTZlZQ==
cache-control: no-cache

Response (HTTP status: 200)

{
  "code": "smf_user_activity",
  "message": "The request has been placed, and soon will be fulfilled",
  "data": {
    "status": 200
  }
}

Remove User

Endpoint

GET /api/v1.0/memberships/#membership_id#/users/#user_id#

Description

Removes the specified user from the the given membership.

Parameters

field	type	optional	description
membership_id	integer	no	ID of the membership the user is registered with.
user_id	integer	no	ID of the user.

The header includes the Authentication Bearer token.

Response

A collection of the data containing each requested day. Each day includes:

field	type	optional	description
status	integer	no	Status 200, indicating the user has been removed.

Example

Request (URLEncoded)

DELETE /api/v1.0/memberships/1840/users/61 HTTP/1.1
Host: sharemyfitness.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWxlMTVAc2hhcmVteWZpdG5lc3MuY29tIiwiZXhwaXJlc19pbiI6MTU0MTYwNzY3M30=.YTFjN2Y2MTJhMTA1ZGQ5ODk1ZDE5ZjgzMzE4NWRlODQ0MzQ0OTNhNGRlYzdiN2JmNjk3MzFmZWZiMWVlZTZlZQ==
cache-control: no-cache

Response (HTTP status: 200)

{
  "code": "smf_remove_user",
  "message": "The user has been removed from your membership",
  "data": {
    "status": 200
  }
}

Error Responses

Error responses should be handled according with the HTTP status reponses. However, explanatory responses are given. Example of those responses, for all methods, are:

code	status	message
smf_auth_failed	403	Invalid credentials
smf_exp_token	403	The token is expired, please authenticate again
smf_missing_token	403	The token is not provided. Please try again providing the token in the header request
smf_invalid_token	403	The token is invalid. Please provide a valid token in the header request
smf_not_found	404	No resource was found matching the request
smf_not_authorized	403	Your membership is not active. It needs to be active to enable access to your users details
smf_invalid_date	400	One provided date is invalid
smf_internal_error	500	Please report this error

Example

{
    "code": "smf_exp_token",
    "message": "The token is expired, please authenticate again",
    "data": {
        "status": 403
    }
}