System
AirBands DynaMo ForceDecks ForceFrame HumanTrak NordBord SmartJump SmartSpeed TeleHab VALD Hub
Contact us

Search

A guide to using the External ForceDecks API

Agent Service Account
  • Updated

This guide is intended to provide instructions on how to interact with and use the External ForceDecks API to access team and athlete test data.

Identify your region

The base URL you use to interact with the External ForceDecks API is dependant on what region your (or your client's) data resides in.

Choose your region and copy the base URL provided below. For access to the Swagger documentation, you can paste and search the URL in your web browser.

Australia (East)
https://prd-aue-api-extforcedecks.valdperformance.com/swagger/index.html
United States (East)
https://prd-use-api-extforcedecks.valdperformance.com/swagger/index.html
Europe (West)
https://prd-euw-api-extforcedecks.valdperformance.com/swagger/index.html

If you are unsure which region-specific URL you should be using, please contact support@vald.com.

Prerequisites

In each example below, it is assumed that the ID for the team(s) (i.e. teamId or tenantId) are obtained using the External Tenants API, and the IDs for individual athlete(s) (i.e. athleteId or profileId) are obtained using the External Profiles API.

Scenario 1: Retrieve a collection of tests

URL

/tests

Path Parameters

None

Query Parameters

Parameter Required Description
tenantId True The ID of the tenant.
modifiedFromUtc True

Filter tests modified since this date and time.

Format: YYYY-MM-DDT00:00:00.000Z
profileId False The ID of the profile to optionally filter on.

Description

  1. Set the parameters:
    1. Retrieve the tenantId parameter from the External Tenants API.
    2. Set the modifiedFromUtc to be the start date of your testing period.
    3. Optionally, retrieve the profileId parameter from the External Profiles API.
  2. Retrieve a collection of tests using /tests?tenantId={tenantId}&modifiedFromUtc={modifiedFromUtc}&profileId={profileId}
  3. The tests in the response are ordered by modifiedDateUtc. To retrieve more tests, update the modifiedFromUtc parameter to match the last test's modifiedDateUtc from the response.
  4. Repeat steps 2 – 3 until a No Content 204 status code is returned.

Response

Example response

{
  "tests": [
    {
      "testId": "<TEST-ID>",
      "tenantId": "<TENANT-ID>",
      "profileId": "<PROFILE-ID>",
      "recordingId": "<RECORDING-ID>",
      "modifiedDateUtc": "2024-06-17T05:23:52.940Z",
      "recordedDateUtc": "2022-06-01T05:53:32.417Z",
      "recordedDateOffset": 600,
      "recordedDateTimezone": "E. Australia Standard Time",
      "analysedDateUtc": "2024-06-17T05:23:53.523Z",
      "analysedDateOffset": 600,
      "analysedDateTimezone": "E. Australia Standard Time",
      "testType": "QSB",
      "notes": "Test notes...",
      "weight": -1,
      "parameter": {
        "resultId": 655381,
        "value": 15
      },
      "extendedParameters": [
        {
          "resultId": 655382,
          "value": 0
        },
        {
          "resultId": 655383,
          "value": 0
        },
        {
          "resultId": 655384,
          "value": 0
        }
      ],
      "attributes": [
        {
          "attributeValueId": "<ATTRIBUTE-VALUE-ID>",
          "attributeValueName": "Attribute Value Name",
          "attributeTypeId": "<ATTRIBUTE-TYPE-ID>",
          "attributeTypeName": "Attribute Type Name"
        }
      ]
    }
  ]
}

Scenario 2: Retrieve a collection of trials (i.e. reps) for a test

URL

/v2019q3/teams/{teamId}/tests/{testId}/trials

Path Parameters

Parameter Required Description
teamId True The ID of the team.
testId True The ID of the test.

Query Parameters

None

Description

  1. Set the parameters:
    1. Retrieve the teamId parameter from the External Tenants API.
    2. Retrieve the testId parameter from the /tests endpoint.
  2. Retrieve a collection of reps / trials using /v2019q3/teams/{teamId}/tests/{testId}/trials

Response

Example response

[
  {
    "id": "<TRIAL-ID>",
    "athleteId": "<LEGACY-ATHLETE-ID>",
    "hubAthleteId": "<ATHLETE-ID>",
    "recordedUTC": "2022-06-01T05:53:32.417Z",
    "recordedOffset": 600,
    "recordedTimezone": "E. Australia Standard Time",
    "startTime": 2.9999999999999583,
    "endTime": 18.000000000000703,
    "results": [
      {
        "resultId": 13500417,
        "value": 0.07883476583591308,
        "time": 18,
        "limb": "Trial",
        "repeat": 0,
        "definition": {
          "id": 13500417,
          "result": "BAL_COP_TOTAL_EXCURSION",
          "description": "Total distance travelled by the CoP",
          "name": "Total Excursion",
          "unit": "Millimeter",
          "repeatable": false,
          "asymmetry": true
        }
      },
      ...
    ],
    "lastModifiedUTC": "2022-06-01T05:53:43.564Z",
    "limb": "Both"
  }
]

Scenario 3: Retrieve a raw test recording

You will need to contact the VALD Support Team (support@vald.com) to request permission to retrieve individual test recordings before using this endpoint.

URL

/v2019q3/teams/{teamId}/tests/{testId}/recording

Path Parameters

Parameter Required Description
teamId True The ID of the team.
testId True The ID of the test.

Query Parameters

Parameter Required Description
includeSampleData False Flag to indicate whether to include all sample data. This will default to False.

Description

  1. Set the parameters:
    1. Retrieve the teamId parameter from the External Tenants API.
    2. Retrieve the testId parameter from the /tests endpoint.
  2. Retrieve a test recording using /v2019q3/teams/{teamId}/tests/{testId}/recording

Response

Example response

{
  "id": "<RECORDING-ID>",
  "athleteId": "<LEGACY-ATHLETE-ID>",
  "hubAthleteId": "<ATHLETE-ID>",
  "recordedUTC": "2022-06-01T05:53:32.417Z",
  "recordedOffset": 600,
  "recordedTimezone": "E. Australia Standard Time",
  "recordingInfo": "ForceDecks;2.0.8181",
  "dataSource": "ForceDecks;FDM1-220526-FW2R7-HW3R2,0132",
  "recordingType": "Dual",
  "recordingOutput": "ForceZ, CentreOfPressureX, CentreOfPressureY, ForceComponents",
  "samplingFrequency": 200,
  "duration": 18.055,
  "lastModifiedUTC": "2022-06-01T05:53:42.304Z",
  "recordingDataHeader": [
    "Time",
    "Z Left",
    "COPX Left",
    "COPY Left",
    "Z Right",
    "COPX Right",
    "COPY Right"
  ],
  "recordingData": [
    [
      0,
      614.49642,
      -30.518276,
      18.338962,
      95.341885,
      -3.696617,
      28.288536
    ],
    ...
  ]
}

Scenario 4: Retrieve result definitions

Option A: Retrieve all result definitions

This will retrieve all result definitions using /resultdefinitions.

This endpoint should be used initially to store a collection of all result definitions. Result definitions do not change frequently. If you received an unfamiliar resultId from the /tests endpoint, it is likely that a new metric has been added since the definitions were last accessed.

You should either retrieve the entire collection again using this method or use the below Option B to add the missing resultId to your collection.

Option A Response

Example response

{
  "resultDefinitions": [
    ...
    {
      "resultId": 6553607,
      "resultIdString": "JUMP_HEIGHT",
      "resultName": "Jump Height (Flight Time)",
      "resultDescription": "Jump height calculated from flight time",
      "resultGroup": "Takeoff",
      "supportsAsymmetry": false,
      "isRepeatResult": false,
      "resultUnit": "Centimeter",
      "resultUnitName": "cm",
      "resultUnitScaleFactor": 1,
      "numberOfDecimalPlaces": 1,
      "trendDirection": "Positive"
    },
    {
      "resultId": 6553608,
      "resultIdString": "JUMP_HEIGHT_RELATIVE_LANDING_RFD",
      "resultName": "Jump Height (FT) Relative Landing RFD",
      "resultDescription": "Jump Height (FT) Relative Landing RFD",
      "resultGroup": "Landing",
      "supportsAsymmetry": false,
      "isRepeatResult": false,
      "resultUnit": "NewtonPerSecondPerCentimeter",
      "resultUnitName": "N/s/cm",
      "resultUnitScaleFactor": 1,
      "numberOfDecimalPlaces": 2,
      "trendDirection": "None"
    },
    {
      "resultId": 6553609,
      "resultIdString": "JUMP_HEIGHT_RELATIVE_PEAK_LANDING_FORCE",
      "resultName": "Jump Height (FT) Relative Peak Landing Force",
      "resultDescription": "Jump Height (FT) Relative Peak Landing Force",
      "resultGroup": "Landing",
      "supportsAsymmetry": false,
      "isRepeatResult": false,
      "resultUnit": "NewtonPerCentimeter",
      "resultUnitName": "N/cm",
      "resultUnitScaleFactor": 1,
      "numberOfDecimalPlaces": 2,
      "trendDirection": "None"
    }
    ...
  ]
}

Option B: Retrieve a specific result definition

This will retrieve a specific result definition using /resultdefinition/{resultId}

Note: The resultID path parameter can be collected from the parameter and extendedParameters properties on the test response from /tests.

Option B Response

Example response


{
  "resultId": 6553607,
  "resultIdString": "JUMP_HEIGHT",
  "resultName": "Jump Height (Flight Time)",
  "resultDescription": "Jump height calculated from flight time",
  "resultGroup": "Takeoff",
  "supportsAsymmetry": false,
  "isRepeatResult": false,
  "resultUnit": "Centimeter",
  "resultUnitName": "cm",
  "resultUnitScaleFactor": 1,
  "numberOfDecimalPlaces": 1,
  "trendDirection": "Positive"
}

Frequently asked questions

Expand All

What do the analysedOffset and recordedOffset values represent?

These values represent the time zone offset in minutes to apply to the UTC value in analysedUtc and recordedUtc for the time of analysis and recording on the application.

Why is the weight value –1?

The weighing step in this recording was skipped. For test types where weight is required for test analysis, if the weighing step was skipped then the weight is estimated prior to each rep and stored in the "Athlete Standing Weight" metric.

We recommend using the "Bodyweight in Pounds" and "Bodyweight in Kilograms" metrics to retrieve weight for all Jump and Functional test types.

What does the limb value represent and how does it differ between trials and results?

For single limb tests (one limb per rep), TrialDTO.Limb is either Left or Right. Each metric result within the trial is for this single limb. TrialResultDTO.Limb will be Trial (inherits the limb value for the result from parent TrialDTO.Limb).

For bilateral tests (two limbs per rep such as a Countermovement Jump), TrialDTO.Limb is Both. Each metric result within the trial contains multiple TrialResultDTO's with different TrialResultDTO.Limb values.

For metrics determined only from the combined Left and Right force (such as jump height), a single TrialResultDTO will be present and it's Limb value will be Both. For metrics with separate Left and Right forces, there will be multiple TrialResultDTO records present with Limb values Trial, Left, Right, and Asym.

In addition, some tests contain multiple repeats within a single trial (for example individual squats within a Squat Assessment). For these, each metric within a TrialResultDTO will include entries for each repeat, with the TrialResultDTO.Repeat field being the zero-based repeat number.

What does the resultUnitScaleFactor value represent?

Metric values given in value are in the unit used internally by the ForceDecks algorithms – typically this is an SI unit.

The unit given by resultUnit indicates the unit the metric is displayed in.

resultUnitScaleFactor indicates what the value must be scaled (i.e. multiplied) by to be in the resultUnit.

What does trendDirection represent?

trendDirection indicates the direction in change of a metric value that ForceDecks considers good.

A trendDirection of Positive indicates that increases in that metric's values are good.

A trendDirection of Negative indicates that decreases in that metric's values are good.

A trendDirection of None indicates that a metric is more nuanced and there isn't a consistent positive or negative interpretation for it.

Comments

0 comments

Please sign in to leave a comment.

Related articles