Preparation

Pacer OpenAPI domain name openapi.mypacer.com

To use the Pacer OpenAPI, please take the following steps:

  • Register to be a Pacer Developer at http://developer.mypacer.com.
  • Create a client account on the developer console.
  • Save your client_id and client_secret on your server. This key pair of values is used for authorization.

Authorization

Pacer OpenAPI follows the OAuth 2.0 Authorization Code Grant which includes 4 steps:

  • The developer client redirects users to Pacer’s authorization website with client_id and redirect_uri
  • After the user approves the request, Pacer’s authorization server redirects the browser back to the developer website at redirect_uri with code and state and auth_result
  • The developer client exchanges the code for an access_token
  • The access_token expires after a period of time as expires_in. The developer client should request a new access_token via refresh_token when it would be expired

AuthWeb

Pacer OpenAPI uses the OAuth 2.0 Authorization Code Grant. Developer clients must redirect users to Pacer’s authorization website. The web authorization url is: http://developer.mypacer.com/oauth2/dialog?client_id=${client_id}&redirect_uri=${redirect_uri}&state=${state} which contains client_id, redirect_uri and state. client_id is generated by the system in the developer console. redirect_uri is the web address for the developer client to handle authorization callbacks. It should be urlEncoded. state is used to keep user custom params passed in OAuth.

RedirectURI

After user authorization, Pacer’s oauth server redirects the web page to the redirect_uri with code, state and auth_result.

  • if the auth_result is fail, this indicates authentication error or that the user cancelled the authorization.
  • otherwise auth_result should be success and there should be a query code in urlQuery. This code expires in a few minutes, so the developer should exchange it for an access token by code immediately. Once the access_token is successfully returned to the client then the code expires. Each code can be used only once.

CreateAccessToken

In the access token creation API, you should include Authorization: ${encodedSignature} in your http request header. The encodedSignature has a simple algorithm:

    String appSecretHash = MD5(client_secret + "pacer_oauth");
    String encodedSignature = MD5(appSecretHash + client_id);

The MD5() function uses the standard MD5 algorithm and returns a lowercase string of 32 characters.

POST /oauth2/access_token

Headers

Authorization: ${encodedSignature}
Content-Type: application/json

Body

{
    "client_id": ${client_id},
    "code": ${code},
    "grant_type": "authorization_code"
}

Response

{
    "success": true/false,
    "status": 200,
    "data": {
        "access_token": "xxx",
        "refresh_token": "xxx",
        "expires_in": 86400,
        "user_id": "xxx"
    }
}

refreshAccessToken

The Authorization header uses the same generation algorithm as create token above.

POST /oauth2/access_token

Headers

Authorization: getAuthorization()
Content-Type: application/json

Body

{
    "client_id": ${client_id},
    "refresh_token": ${refresh_token},
    "grant_type": "refresh_token",
}

Response

{
    "success": true/false,
    "status": 200,
    "data": {
        "access_token": "xxx",
        "expires_in": 86400,
        "user_id": "xxx"
    }
}

API Call

Developers can currently access Pacer user info and activities. In the general api, the Authorization header should be a string with the following info:

Authorization = "Bearer " + access_token

Pacer OpenAPI always returns http 200 status codes except in the case of a network error or server bug. Logic or param errors, like an invalid access token or code, are returned in the response body. This means that if Pacer OpenAPI is sent a bad request, it will still return a 200 response code so developers should check the response body for errors.

getUserInfo

GET /users/:user_id

Response

{
    "success": true/false,
    "status": 200,
    "data": {
        "user_id": "xxx",
        "display_name": "xxx",
        "avatar_path": "xxx"
    }
}

getDailyActivitySummary

The start_date and end_date values should be within the past 31 days

GET /users/:user_id/activities/daily.json?start_date=2018-09-01&end_date=2018-09-10&accept_manual_input=true

response

{
    "success": true,
    "status": 200,
    "data": {
        daily_activities: [
                {
                    recorded_for_date: "2018-08-31",
                    steps: 4567,
                    walking_running_distance: 3632,
                    cycling_distance: 0,
                    swimming_distance: 0,
                    total_distance: 3632,
                    calories: 204,
                    active_time: 2873,
                    source: "Pacer"
                }
        ]
    }
}

getSessionActivities

The start_date and end_date values should be within the past 31 days

GET /users/:user_id/activities/session.json?start_date=2018-09-01&end_date=2018-09-10

response

{
    "success": true,
    "status": 200,
    "data": {
        session_activities: [
                {
                    id: 1445768909876,
                    recorded_for_date: "2018-08-31",
                    recorded_for_datetime_iso8601: "2018-08-31 09:23:13T+08:00",
                    steps: 4567,
                    distance: 3842,
                    calories: 204,
                    active_time: 2873,
                    type: "GPS Running Walking",
                }
        ]
    }
}

The possible values returned for activity attribute type are listed in the table below.

  • "Tracked by Sensor" indicates whether the activity was tracked by a hardware sensor or manually input.
  • Hardware sensors include a device’s accelerometer, pedometer, GPS or other sensors. Devices include a user’s phone, or Fitbit, Apple Watch or other Pacer-compatible devices.
  • True indicates activities that Pacer is able to track using hardware above, (like GPS walking).
  • False indicates activities that Pacer cannot track using hardware above (like a yoga session).
  • When the accept_manual_input value of getDailyActivitySummary set to true, all types of session activity (including manually input data) will be counted in daily summary data.
  • When this value is set to false, only activity types tracked by a hardware sensor (TRUE for Tracked by Sensor in the table above) will be counted in daily summary data.
Session Activity Types Tracked by Sensor
GPS Running Walking TRUE
GPS Cycling TRUE
Indoor Session TRUE
Cardio Workout TRUE
Strength Workout TRUE
Apple Health Cycling TRUE
Fitbit Session TRUE
Aerobic FALSE
Bicycling FALSE
Jogging FALSE
Running FALSE
Custom FALSE
Sports FALSE
Walking FALSE
Swimming FALSE
Yoga FALSE
Dancing FALSE
Hiking FALSE
Fitbit Manual Input FALSE