Documentation

Documentation can be found here.

Overview

mrthn (pronounced marathon) is a web service whose purpose is to make integration with multiple fitness apps effortless for developers. Instead of choosing to individually integrate with one or many fitness apps, developers can instead integrate with mrthn, which allows their users to sign up with compatible fitness apps. mrthn takes care of signing up and authenticating the users for the developers, and our easy to use APIs allows app creators to query their users fitness data.

• If you have any questions or suggestion, email us at info@mrthn.dev

Registering an Account and Requesting Authorization

To be able to access the mrthn API, you need to register as a Client and generate an authorization token. You can register for free here. After registering, you'll be redirected to your profile page. There, you can generate your token and set your callback URL. See the User Login section below for more information on the callback URL.

User Login

To authenticate a user with mrthn, you have to redirect them to https://mrthn.dev/service.html within a web browser. There, your user can select with platform they would like to authenticate with and be redirected to their login page. Once they are finished with authentication, we will redirect them back to your callback URL (set in your Profile page), with a URL query parameter containing their new user ID. You can then use that user ID to request their data through mrthn.

Resource URL

https://mrthn.dev/service.html?token=[token]
        

Parameters	Optional/Required	Description
token	required	Your Access Token, available on your profile page
userID	optional	The ID of the user you want to link an extra account

Considerations

1. This endpoint should be accessed through a browser. Redirect your users from your app to https://mrthn.dev/service.html so they can be authenticated.
2. After your user has finished authenticating, they will be redirected to the callback URL that was set in your Client account. The URL will have a query parameter containing the ID of the User that was just authenticated (e.g. ?userID=4). You can then use that ID to request their data (See Requesting Data).
3. An optional userID parameter can be passed to identify that the user you are trying to authenticate is already registered with mrthn, but wants to link another platform account (e.g. User created their account using their Fitbit credentials, but now they want to link their Google Fit account).
4. If any errors occurred during the login flow, you will receive an userID of 0 as part of the query params.

Requesting Data

Authorization

Access Token: The access token must be passed as part of the HTTP request for every query. It is passed as part of the authorization header, in the following format:

Authorization: Bearer [access-token]
        

Test the API

You can perform test calls to mrthn's endpoints by going to the SwaggerHub page. Once there, click the Authorize button and enter your Access Token to be able to performs calls.

Endpoints

Get Daily Values

The Get Daily Values endpoint retrieves the quantity of a specific value (steps, calories, or distance) of a given user on a specific date, separated by platform.

Resource URL

GET https://api.mrthn.dev/user/[user-id]/[resource]/daily?date=[date]
        

Parameters	Description
user-id	ID of the user to retrieve data from
resource	The type of data you want to retrieve. Can be steps, distance, or calories
date	The date in the format yyyy-MM-dd
largestOnly (optional)	Boolean. Set it to true to only return the largest value platform.

Considerations

1. The response will contain an array of values, named after the request's value-type parameter.

Example Response

{
            "id": 1,
            "steps": [
                {
                    "platform": "google",
                    "value": 1659
                },
                {
                    "platform": "fitbit",
                    "value": 1789
                }
            ]
        } 
        

Get Values Over Period

The Get Values Over Period endpoint retrieves the quantity of a specific value (steps, calories, or distance) of a given user over a period of time, separated by platform.

Resource URL

GET https://api.mrthn.dev/user/[user-id]/[resource]/over-period?date=[date]&period=[period]
        

Parameters	Description
user-id	ID of the user to retrieve data from
resource	The type of data you want to retrieve. Right now, only distance is supported
date	The date in the format yyyy-MM-dd
period	The range for which data will be returned. Options are 1d, 7d, 30d, 1w, 1m, 3m, 6m
largestOnly (optional)	Boolean. Set it to true to only return the largest value platform.

Considerations

1. The response will contain an array of values, named after the request's value-type parameter.

Example Response

{
            "id": 1,
            "distance": [
                {
                    "platform": "google",
                    "value": 20003
                },
                {
                    "platform": "fitbit",
                    "value": 1002
                }
            ]
        }