NAV Navbar
shell
  • Introduction
  • Authentication
  • Activities
  • Users
  • Groups
  • Errors
  • Introduction

    FitRankings provides a simple and powerful REST API to authenticate, integrate and consume 3rd party fitness application data.

    This API reference provides information on available endpoints and how to interact with the FitRankings API.

    Authentication

    To access to the FitRankings OAuth2 API, contact support@fitrankings.com. Upon approval, you will be given a client id and client secret. These credentials will be used to retrieve a master token for your application to include in subsequent requests.

    Master Token

    curl -X "POST" "https://api.fitrankings.com/iq/tokens/master-token/" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d $'{
      "client_id": "...",
      "client_secret": "..."
    }'
    

    The above command returns JSON structured like this:

    {"token": "MASTER_TOKEN"}
    

    To obtain a client application’s master token, one must send a request as indicated, with the client credentials provided to you included in the request body. Thereafter this token must be stored and used with subsequent requests for application-level resources.

    User Authentication

    open "https://api.fitrankings.com/iq/oauth2/?client_id=...&callback_uri=https:%2F%2Fwww.example.com%2F"
    

    Once authorized, the user will be redirected to the callback uri, such as:

    https://www.example.com/?token=USER_TOKEN&user_id=000000
    

    Save the credentials from the query string for subsequent requests.

    In order to access resources (activities, users, etc.), an application must be granted permission by the resource owner. To do so, the client application must direct the owner to our authorization endpoint. We recommend doing so in a 400x600 popup (see example). See below for the necessary query parameters to include in your request. Once the owner has authorized the client application, (s)he will be given the opportunity to connect with a selection of 3rd party fitness devices. After doing so, (s)he will be returned to the callback_uri provided by the client. If the owner has successfully authorized the client, the callback_uri will contain a unique identifier and access token for the client application to use in subsequent requests for the owner’s resources.

    URL Parameters

    Parameter Description
    client_id The client_id provided to you.
    callback_uri If one isn't provided, the last one used will be reused.

    Activities

    Get All Activities

    curl "https://api.fitrankings.com/iq/activities/" \
      -H "Authorization: Bearer USER_OR_MASTER_TOKEN"
    

    The above command returns JSON structured like this:

    [{
          "id": 685612,
          "title": null,
          "description": null,
          "met_minutes": "23.0000",
          "distance": "16009.3440", //meters**
          "duration": "600.0000", //seconds**
          "steps": 111,
          "calories": "22.0000",
          "provider_image_url": null,
          "provider_key": "fitbit",
          "provider_activity_id": "8222125504",
          "activity_type": "1",
          "fitness_type": "2",
          "action_date": "2017-06-13T12:00:00Z",
          "is_locked": false,
          "is_edited": false,
          "is_manual_entry": false,
          "is_deleted": false,
          "created_at": "2017-06-23T17:14:28.840028Z",
          "updated_at": "2017-06-23T17:14:28.840053Z",
          "user": {
            "id": 30171,
            "email": "john@gmail.com",
            "first_name": "John",
            "last_name": "Smith",
            "date_joined": "2017-06-23T17:14:10.995721Z",
            "handle": null,
            "profile": {
              "id": 10494,
              "display_name": "J. Smith",
              "display_name_format": "0",
              "image_profile_url": null,
              "is_private": false,
              "follower_count": 0,
              "following_count": 0,
              "bio": null
            }
          },
          "current_user_reacted_with_type": -1,
          "like_count": 0,
          "comment_count": 0,
          "comments": []
        }, ...]
    

    Retrieve a list of all activities related to a user or client (ordered by date).

    HTTP Request

    GET https://api.fitrankings.com/iq/activities/

    URL Parameters

    Parameter Default Description
    page 1 The page to jump to. Optional.
    page_size 20 The amount of results to include per page. Optional.

    Get a Specific Activity

    curl "https://api.fitrankings.com/iq/activities/<ID>/" \
      -H "Authorization: Bearer USER_OR_MASTER_TOKEN"
    

    The above command returns JSON structured like this:

    {
      "id": 685775,
      "title": null,
      "description": null,
      "met_minutes": "182.0000",
      "distance": "0.0000", //meters**
      "duration": "5460.0000", //seconds**
      "steps": 3347,
      "calories": "0.0000",
      "provider_image_url": null,
      "provider_key": "google-oauth2",
      "provider_activity_id": "1502064788614000000",
      "activity_type": "1",
      "fitness_type": "1",
      "action_date": "2017-08-07T00:00:00Z",
      "is_locked": false,
      "is_edited": false,
      "is_manual_entry": false,
      "is_deleted": false,
      "created_at": "2017-08-08T17:08:24.310110Z",
      "updated_at": "2017-08-08T17:08:24.310137Z",
      "user": {
        "id": 30264,
        "email": "bob@aol.com",
        "first_name": "Bob",
        "last_name": "Smith",
        "date_joined": "2017-06-21T17:52:32.795423Z",
        "handle": null,
        "profile": {
          "id": 10493,
          "display_name": "Bob",
          "display_name_format": "1",
          "image_profile_url": "https://d2qqvi7evhy56u.cloudfront.net/c19757295d946c50e1117f2b34a1481373516c4a.png",
          "is_private": false,
          "follower_count": 0,
          "following_count": 0,
          "bio": null
        }
      },
      "current_user_reacted_with_type": -1,
      "like_count": 0,
      "comment_count": 0,
      "comments": []
    }
    
    

    This endpoint retrieves a specific activity by id.

    HTTP Request

    GET https://api.fitrankings.com/iq/activities/<ID>/

    URL Parameters

    Parameter Description
    ID The ID of the activity to retrieve.

    Users

    Get All Users

    curl "https://api.fitrankings.com/iq/users/" \
      -H "Authorization: Bearer USER_OR_MASTER_TOKEN"
    

    The above command returns JSON structured like this:

    [{
        "id": 30267,
        "email": "aaron@smith.com",
        "first_name": "Aaron",
        "last_name": "Smith",
        "date_joined": "2017-08-07T19:11:51.971815Z",
        "handle": null
      }, ]
    

    Retrieve a list of all activities related to a user or client (ordered by date).

    HTTP Request

    GET https://api.fitrankings.com/iq/users/

    URL Parameters

    Parameter Default Description
    page 1 The page to jump to. Optional.
    page_size 20 The amount of results to include per page. Optional.

    Get a User's Stat Summary

    curl "https://api.fitrankings.com/iq/users/stat-summary/" \
      -H "Authorization: Bearer USER_OR_MASTER_TOKEN"
    

    The above command returns JSON structured like this:

    {
        "calories": 46272.1676,
        "duration": 381845.0, //seconds**
        "distance": 766966.1322, //meters**
        "user_id": 30264,
        "met_minutes": 42186.1016,
        "steps": 713047
      }
    

    This endpoint retrieves a user's aggregate stats for the given time period.

    HTTP Request

    GET https://api.fitrankings.com/iq/users/stat-summary/

    URL Parameters

    Parameter Default Description
    time_mode 0 (all-time) The period to aggregate stats for. 1 = Year, 3 = Month, 4 = Week, 5 = Day. Optional.
    time_value NA The time period to use in conjunction with the time_mode. YYYY, YYYY-MM, YYYY-WW, YYYY-MM-DD. Optional.
    start NA YYYY-MM-DD HH:MM:SS Optional.
    end NA YYYY-MM-DD HH:MM:SS Optional.

    Groups

    Get A Group's Stat Summary

    curl "https://api.fitrankings.com/iq/groups/stat-summary/" \
      -H "Authorization: Bearer MASTER_TOKEN"
    

    The above command returns JSON structured like this:

    {
      "group_id": 619,
      "avg_user_met_minutes": 11092.975341666666,
      "calories": 133191.6932,
      "activities": 188,
      "duration": 1129205.0, //seconds**
      "user_count": 12,
      "distance": 1205322.8494, //meters**
      "met_minutes": 133115.7041,
      "steps": 1155501
    }
    

    Retrieve aggregate stats for a group’s members.

    HTTP Request

    GET https://api.fitrankings.com/iq/groups/stat-summary/

    URL Parameters

    Parameter Default Format
    time_mode 0 (all-time) The period to aggregate stats for. 1 = Year, 3 = Month, 4 = Week, 5 = Day. Optional.
    time_value NA The time period to use in conjunction with the time_mode. YYYY, YYYY-MM, YYYY-WWW, YYYY-MM-DD. Optional.
    start NA YYYY-MM-DD HH:MM:SS
    end NA YYYY-MM-DD HH:MM:SS

    Errors

    The FitRankings API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request has an error. Check parameters and formatting.
    401 Unauthorized -- Your API key is invalid.
    403 Forbidden -- Your API key does not have appropriate permissions.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.