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

Search

A guide to using the External SmartSpeed API

Agent Service Account
  • Updated

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

Identify your region

The base URL you use to interact with the External SmartSpeed 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-extsmartspeed.valdperformance.com/
United States (East)
https://prd-use-api-smartspeed.valdperformance.com/
Europe (West)
https://prd-euw-api-extsmartspeed.valdperformance.com/

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.

High level test summaries vs Detailed test information

The high-level test summaries provide digestible information of the test results. This information includes results such as total test time, max velocities and others.

The detailed test information contains all the data recorded within the test. This information includes individual split timings between gates or the individual jump results recorded within the test.

Some test metrics are not available within the test summary and only available within the detailed test information.

Calling the detailed test information endpoint for a test is only required if the test summary information is inadequate for the use case.

Scenario 1: Retrieve a collection of high-level test summaries

URL

/v1/team/{teamId}/tests

Path Parameters

Parameter Required Description
teamId True The ID of the tenant or team from which to retrieve tests.

Query Parameters

Parameter Required Description
athleteId False The ID of the athlete to optionally filter on.
testFromUtc False

Retrieve tests recorded after the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
testToUtc False

Retrieve tests recorded before the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
modifiedFromUtc False

Retrieve tests modified after the specified UTC date.

Format: YYYY-MM-DDT00:00:00.000Z
groupUnderTestId False Retrieve tests that were recorded for a specific group of athletes.
page True Specify the page number to iterate through paged results.

Description

To iterate through the total pages using the test endpoint, use the following steps.

  1. Set currentPage variable to 1.
  2. Retrieve the first page of data using /v1/team/{teamId}/tests?ModifiedFromUTC={timestampOfLastRequest}&Page={currentPage}.
  3. Save the date and time of the request into the timestampOfCurrentRequest variable.
  4. Check if the returned data array is empty or contains tests.
    1. If contains tests:
      1. Increment currentPage by 1.
      2. Retrieve the next page using /v1/team/{teamId}/tests?ModifiedFromUTC={timestampOfLastRequest}&Page={currentPage}.
      3. Return to the start of step 4.
    2. If empty:
      1. There is no more data to retrieve.
      2. Set timestampOfLastRequest to the value in timestampOfCurrentRequest.

Response

Property Description
id The unique identifier for the test.
profileId The unique identifier of the athlete who performed the test.
groupUnderTestId The group that was selected when the test was performed.
testName The name of the test type.
testTypeName An enum representing the high-level type of the test.
repCount The number of reps contained within the test.
deviceCount The number of devices used when the test was performed (e.g. 4 gates).
testDateUtc

The UTC date the test was performed.

Format: YYYY-MM-DDT00:00:00.000Z
isValid Validity flag which represents the valid / invalid tag applied to a test.
allGroups List of unique group identifiers the athlete belonged to at the time of testing.
additionalOptionsFields JSON object containing high level important parameters used for the test (see Swagger page for full details).
runningSummaryFields JSON object containing fields for running test types which contain the summarized test data (see Swagger page for full details).
jumpingSummaryFields JSON object containing fields for jumping test types which contain the summarized test data (see Swagger page for full details).

Scenario 2: Retrieve the detailed information for a specific test

URL

/v1/team/{teamId}/tests/{testId}/detail

Path Parameters

Parameter Required Description
teamId True The ID of the tenant or team from which to retrieve tests.
testId True The ID of the test to retrieve.

Description

Use these steps to retrieve the detailed information for a specific test.

  1. Find the testId using the /v1/team/{teamId}/tests endpoint.
  2. Retrieve the specific test information using /v1/team/{teamId}/tests/{testId}/detail.

Response

Property Description
sessionId The unique identifier for the testing session that the test was performed within.
profileId The unique identifier of the athlete who performed the test.
groupUnderTestId The group that was selected when the test was performed.
testDateUtc

The UTC date the test was performed.

Format: YYYY-MM-DDT00:00:00.000Z
trialIndex The number of the test within the testing session.
tag 'Valid' or 'Invalid' tag which identifies tests that were tagged as invalid.
additionalTestResult JSON object containing fields which are important for specific test types (see Swagger page for full details).
repResults A list of JSON objects containing the low-level fields recorded for a test, e.g. split timings (see Swagger page for full details).

Comments

0 comments

Please sign in to leave a comment.

Related articles