¶ Kinatrax API
The API is used to give Kinatrax Trial data access to end users.
¶ Getting Started
Getting logged onto the application is easy, but here is the different options that are available through the API.
¶ Login
If you have a valid account, use your account email and password to login.
¶ Registering an Account
Users have the ability to self register to the platform. All users accounts will be validated by an admin, and require a confirmed email. You will receive several emails with instructions, and status of your account.
To create an account, click “Need An Account” button.
Fill in your information.
From here you should receive emails to finish your account.
¶ Need Help Logging in?
If you account is not confirmed, or you have been locked out from two many password attempts there is an easy way to recover or activate your account.
¶ Confirm Account
All accounts within the API must be confirmed. When your account is created an email will be sent to you that you must follow to validate your email. If you did not receive this email you can have the system resend a confirmation email to you by entering you email into the resend confirmation form field.
¶ Forgot Password
If you forgot your password you can use the forgot password form to send a secure link to reset you account password.
¶ Locked Account
If you account becomes locked because of three failed password attempts you will have you unlock your account. Use the unlock account form to get a secure unlock link.
¶ Trials Section
The Trial section of the API will provide access to Trial data that has been uploaded into the API.
¶ Trial List View
The list of all the Trial data your account has access too.
¶ Mass Link Trials
This will allow multiple links at the same time instead of individually. Select a player and a company, then hit link and you are all set!
¶ Mass Link Trials By Name
This will allow multiple trials to be linked to companies at the same time instead of individually. To use this, input the part of the file name of the records you wish to link, and select the company. The system will then search for the matching records and display the number of matches on screen. If you would like to inspect the matches, click the show button. From here you can deselect any of the records you do not wish to link to the company. Once satisfied click link, and the system will apply the company linkage to the trial data.
¶ Mass Unlink Trials by Name
You can also unlink multiple trials by following a similar process to Mass Linking Trials. Search part of the file name you wish to access, and select a company. From there, you can view the matched trials, remove the flag on certain trials for Unlinking if you wish, and proceed with the Unlinking process.
¶ Mass Re-link Trials
You can also re-link multiple trials that may have lost there linkage to do an error. If the trial has not been previous linked using a stored file path, or Acronym then manual intervention will be required.
¶ Mass Link Trials By Acronym
You can link multiple trials using a stored file path, or Acronym then manual intervention will be required.
¶ Mass Delete Trials by ID
Admins have the ability to delete trials by providing the ID or range of ids.
¶ Download Trial
Once in the General Information section, there is a button that will allow the trial for that specific player to be downloaded as a JSON file to your workstation/computer.
¶ Trial Deletion
Trials can be deleted in the security tab. Deleting trial data is not reversible.
¶ Companies Section
This feature is available for Admins only. Admins can create companies, assign permissions, update, and disable companies in the section.
¶ Companies List
This displays all the companies configured in the system.
¶ Create a Company
Admins have the ability to create a company in the system by clicking the create button and filling out the form.
¶ Auto Link Trials to a Company
This allows a file path to be entered so the API knows what files should be automatically linked to a company based on the trial data path. Under the General Information section, there is a smaller area where File Paths to Auto-Link can be placed.
¶ Company Permissions
The company permissions will allow companies access to data based on the items selected. Only items selected in the subcategories: (Venues, Teams, Players, and Trials) will be available for companies to download.
¶ Venues
This will allow data that is from a specific venue.
¶ Teams
This will allow data that is from a specific teams.
¶ Players
This will allow data that is from selected players.
¶ Trials
This will allow data that is from a selected trials. Trial records are loaded 1000 at a time.
¶ Company Downloads
Shows how many logs, who downloaded them, and when they were created.
¶ Company Users
Displays the company users with info on their ID, first name, and last name.
¶ Company Sharing
Companies data can be shared by creating sharing rules. To view the company sharing list for each company click on company sharing in the particular company.
¶ Add a Sharing Rule
To add a sharing rule click ADD. Select the appropriate settings for this sharing rule then click save.
¶ View\Edit a sharing Rule
To view and edit a share rule click the edit button on the rule in the list view.
¶ Delete a Sharing Rule
To delete a share rule click the delete button on the rule in the list view.
¶ Company Deletion
Companies can be deleted in the security tab. Deleting a company is not reversible.
¶ Disable Company
Companies can be disabled instead of being delete. This action will lock out the Company from being used.
¶ Enable Company
By default Companies are disabled and must be enabled. Enabling an Company will unlock it and make it available for use.
¶ Connections Section
This sections allows accounts to generate API keys which can be used to access the API interface.
¶ Connections List
This will be the list of all the API keys your account has access too.
¶ Create a Connection
To create a connection to generate API access use the create button, and fill out the form.
¶ Generate API Key
Use the generate button to create an API key.
¶ Set Allowed API IP Access
You must whitelist the IPs that can use an API Key. Multiple IPs can be used by separating the addresses with a comma.
¶ API Expiration Date
API keys can be assigned an expiration date. The generate button will auto fill a 30 day expiration. If you would like the key to never expire, do not insert a date.
¶ Convert Key to System Key
Admins have the ability convert existing API keys to system keys. System API keys authorization process is handled different from standard API keys. System keys provide good access to cron jobs and third party applications for pulling an
¶ System Key Origins
For an added layer of security, System Keys require the origin of where the key will be called from. Multiple origins can be added by separating them with a comma. WARNING: To bypass this put UNKNOWN in this field to whitelist all origins.
¶ Endpoints Section
This section is for Admins only. Admins have the ability to add a StackCast account to do lookups on data that has been imported. Only one StackCast account can be active at a time.
¶ Endpoint List
This is the list of all the StackCast accounts saved into the system. This list will show you which account is active.
¶ Endpoint Create
Admins have the ability to create an Endpoint by using the button and filling out the form. The password of an Endpoint is encrypted and saved in the database. Caution should still be used to not reveal hashing keys to allow decrypting of the password.
¶ Endpoint Deletion
Endpoints can be deleted in the security tab. Deleting an account in not reversible.
¶ Disable Endpoint
Endpoints can be disabled instead of being delete. This action will lock out the Endpoint from being used.
¶ Enable Endpoint
By default Endpoints are disabled and must be enabled. Enabling an Endpoint will unlock it and make it available for use.
¶ Generate Access Tokens
StackCast requires a access token to be created to use their API. This can be generated by clicking the generate button. Only one token will be active at a time. Generating a token overwrites the existing token.
¶ Teams Section
This section is for Admins only. Admins have the ability to view and modify Teams pulled in from StackCast.
¶ Teams List
This is the list of all the teams saved into the system. This list will show you which account is active.
¶ Team Show
This section displays the information about the team and allows for adding a site acronym to the team which is used can be used to search on.
¶ Team Deletion
Teams can be deleted in the security tab. Deleting an team may cause linking issue with data.
¶ Dropbox Section
The API allows connecting Dropbox accounts for creating share links for videos linked to companies.
¶ Dropboxes List
This section displays on the configured Dropbox accounts.
¶ Create Dropbox
To create a Dropbox record, select “Create Dropbox” from the table drop down menu. Then fill out the form with your accounts Dropbox Account information.
¶ Authorizing Dropbox Connection
Once the Dropbox record has been created you must authorize the application to have access to you files. Visit the configuration tab of the newly created record. Click the “Authorize Connection” button and follow the onscreen permissions.
¶ Connection Warning
You may receive a connection warning because the application is used by a small subset of users and not yet trusted by Dropbox. You can continue the process by accepting the warning.
¶ Successful Connected Dropbox
Once you have successful connected to Dropbox the Dropbox Explorer should display your folders and files.
¶ Navigating the Dropbox Explorer
The Dropbox explorer allows you to path through folders, and even download files. To path into a folder click on the folder, to go back one layer click up one, to go back to the root of the file system click ROOT DIR. To download a file, click on the name of the file.
¶ Creating Scoped App
To create connect scoped applications for connecting company account use the Dropbox Developer with the following settings.
¶ Redirect URLS
https://api.kinatrax.com/dropboxes/authorize_complete
For Staging use:
https://api-staging.pro-techspecialtys.network/dropboxes/authorize_complete
¶ Permissions
account_info.read
files.metadata.read
files.content.read
sharing.write
sharing.read
¶ Branding
App Name Kinatrax API
Publisher Pro-Tech & Consulting
Description Bringing the benefits of next generation markerless motion capture to baseball.
App website https://api.kinatrax.com
App icons (Download the following).
https://cloud.pro-techspecialtys.network/index.php/s/ZRnXxF5TRXw2Tnj
https://cloud.pro-techspecialtys.network/index.php/s/92pqGKetSygZpeP
¶ Users Section
This Section is used for managing user accounts.
¶ Users List
This is the list of user accounts that your account has access too.
¶ User Account
This is the show view of a user. You can edit users' info in this view.
¶ User Permissions
There are four permissions. Admin, Manager, User Level Two and User. Admin has full control. Manager has elevated control. User Level Two has basic access with the added ability to upload User based data into the API. User has base level permission. Most accounts should be assigned User level permissions.
¶ Change Password
To change an account password go into the security tab and fill out the change password form.
¶ Delete a User
To delete a user go into the account tab and submit the deletion button. Deleting an account is not reversible.
¶ Lock a User Account
Admins have the ability to lock out a user account. Admins can go into the account tab and submit the disable button.
¶ Unlock a User Account
Admins have the ability to unlock a user's account. Admins can go into the account tab and submit the enable button.
¶ Account Masquerading
Admins have the ability to audit users access through Account Masquerading. Admins access this through the Account section on a users record.
To logout as the user, use the exit Masquerade in the top menu.
¶ Account Activation
All admins within the API will receive an email that a new user has registered and needs to be approved. Follow the link in the email to be directed to the activation section of the users profile. When activating new user accounts, ensure to update the user with the approach company.
¶ Account Deactivation
Admins within the API have the ability to deactivate user accounts. This provides similar functionality to locking a user's account, but the feedback given to users is different from a standard lock out.
¶ User Downloads
This section displays all the trials the users have downloaded. This is used for auditing, and tracking transfer of data.
¶ User Rate Limiting
Individual users can be rate limited by adjusting the appropriate settings in the users profile. This is available for admins only.
¶ Common UI Features
Here is a list of features and location of common UI elements.
¶ List Menu
This menu is accessed through the gear box on the list views. It has actions related to the section your within.
¶ Main Menu
This is the top navbar. This is another way to access each section.
¶ Main Menu Gear Menu
This is a drop down menu with more features and tools.
¶ Refresh a List
List automatically refresh, but there is two locations to manually refresh a list view. In the top menu, and list menu.
¶ Message Center
The API features a message system for receiving system generated messages. In the UI, users can view, interact, and clear all notifications.
¶ Tracking Center
The tracking center allows Admins to monitor what trials are in the queue to be processed.
¶ API Data Interface
This interface is used for programmatically retrieving data from the API.
¶ API Base URL
The base URL is the beginning part of all queries to extract data from the API. Think of it as the address where the API lives.
https://api.kinatrax.com
¶ API Query URI
All requests to the API Data API must be called to the below path appended to the Base URL.
/apiv1/trials/
¶ API Data Format
The API features many different formats to retrieve the data from the database. Use the following format actions to retrieve the file format you desire. The format action needs to be appended to the API URI in the query URL.
CSV: gather.csv
JSON: gather.json
¶ Example
This returns a Zipped CSV file containing the data.
/apiv1/trials/gather.csv
¶ API Key
All transactions with the API data interface requires an API key and a valid user. You must first create a key in the API GUI, and enable it to access data from the API data interface. The API Key needs to be appended to the API Data Format in the query URL. The token must have a lead ? in order for it to be passed to the API interface.
When queuing the API data interface the key must be passed in. Use the below option for passing in the key.
token
¶ Example
This returns a Zipped CSV file containing the data.
/apiv1/trials/gather.csv?token=<replace with your key>
¶ API Stream Type
The API features four different ways to stream JSON data. Each can be selected by passing in the stream type as a parameter when querying data. The API will automatically stream CSV as a zip folder, and automatically stream a SQL file without the additional parameter.
The parameter key is:
stream_type
The parameter options are:
json By default this is the standard stream protocol. This method streams an array of JSON objects. Output header type: application/json
ndjson The method streams JSON objects as individual objects one at a time. Output header type: application/x-ndjson
ndjson-arry The method streams JSON objects as individual objects one at time then combines them as an array. (Another good method for file downloads using the web browser.) Output header type: application/x-ndjson
event The method is event based streaming which is good for integrating with front end code. This method treats each object as an event which is triggered to the client. Very similar to web sockets, with out the socket. Output header type: text/event-stream
¶ Example
This returns a JSON download file containing the data requested.
/apiv1/trials/gather.csv?token=<replace with your key>&stream_type=ndjson-arry
¶ API Query Options
The API features many different options for extracting data. The following options can be used to refine the returned data. All options must be appended to the API key with an & in the query URL. More than one query option can be used at time by combining the options with an & . Not adding Query options will result in the complete return of stored data. All values for options must be proceed by a =to be applied.
not_download This returns all data that a company has not downloaded.
created_after This returns all data created after the provided date. (Y-m-d or m-d-Y format Ex. 2022-12-15 or 12-15-2022)
created_before This returns all data before after the provided date.(Y-m-d or m-d-Y format Ex. 2022-12-15 or 12-15-2022)
updated_after This returns all data updated after the provided date. (Y-m-d or m-d-Y format Ex. 2022-12-15 or 12-15-2022)
updated_before This returns all data updated after the provided date.(Y-m-d or m-d-Y format Ex. 2022-12-15 or 12-15-2022)
limit This limits the number of records returned by the number provided.
trial_id This returns all data linked to the provided Trial ID.
game_id This returns all data linked to the provided Game ID.
game_pk This returns all data linked to the provided Game PK.
game_pks_only This returns only Game PKs for the selected records.
player_id This returns all data linked to the provided Player ID.
player_string_id This returns all data linked to the provided string version of Player ID (numbers with leading zeros).
play_guid This returns all data linked with the provided Play GUID.
organization_name This returns all data linked to a company with a name or file path abbreviation that matches the input.
data_source_before This returns all data created after the provided data source date.(Y-m-d or m-d-Y format Ex. 2022-12-15 or 12-15-2022)
data_source_after This returns all data created after the provided data source date.(Y-m-d or m-d-Y format Ex. 2022-12-15 or 12-15-2022)
data_source_id This returns all data related to the the provided data id. The id is constructed from the date time from the report file name: 2022_05_08_16_05_48
data_object This returns all data inside of the given parent data object container. For possible values, see data_object_names_only .
metric_name This returns data from specific column name. For possible values, see metric_names_only .
metric_source This returns data flagged with the corresponding metric source value. For possible values, see metric_source_names_only .
team_name This returns all data linked to the provided Team.
user_not_download This returns all data that the current API user has not downloaded.
list_only This returns a list of the of records matching the query parameters with out the metric data. Pass this option true to enable.
data_type This returns records matching the data type.
game_type This returns records matching the game type.
file_type This returns records matching the file type.
metric_names_only This returns a list of all the metric names from imported files. Pass this option true to enable.
metric_source_names_only This returns a list of all the metric source names from imported files. Pass this option true to enable.
data_object_names_only This returns a list of all the parent data object container names from imported files. Pass this option true to enable.
was_modified This is can be used with not_download and user_not_download to download trials have been updated since the last time the trial was downloaded. Pass this option true to enable.
player_nameThis will allow you to search on the players name. You can provided first or last name, or firstname_lastname (first and lasted joined with a ‘_’).
videos_onlyThis will return only the video file paths for the given search. Pass this option true to enable.
limit_after This limits the output after all search parameters have been applied. (This may result in longer return times)
player_name This returns data that matches the players name. If searching by first and last name join the name with a . Ex. john_doe
data_after This returns the last x number of records from your search.
videos_only This returns only the video related information for a given trial(s).
media_only This returns only data related to the record type Bat, Pitch, etc. Ex. a Bat record will only output Bat data.
include_frame_pitch_data This returns the KeyFrameIndices of all the related pitch as PitchKeyFrameIndices. Pass this option true to enable.
¶ Example
This Example returns a CSV with data linked to player one.
/apiv1/trials/gather.csv?token=SomeHardKey&player_id=1
¶ API Multi Query Options
The following fields will allow you to select multiples by separating values with commas.
trial_id This returns all data linked to the provided Trial ID.
game_id This returns all data linked to the provided Game ID.
player_id This returns all data linked to the provided Player ID.
player_string_id This returns all data linked to the provided string version of Player ID (numbers with leading zeros).
play_guid This returns all data linked with the provided Play GUID.
organization_name This returns all data linked to a company with a name or file path abbreviation that matches the input.
data_source_id This returns all data related to the the provided data id. The id is constructed from the date time from the report file name: 2022_05_08_16_05_48
metric_name This returns data from specific column name.
team_name This returns all data linked to the provided Team.
metric_source This returns data flagged with the corresponding metric source value. For possible values, see metric_source_names_only .
data_object This returns all data inside of the given parent data object container. For possible values, see data_object_names_only .
tags This returns data that matches user's provided tags.
site_acronym This returns data that matches the provided site acronym.
¶ Example
This Example will returns data linked to player one, two, three, and four.
/apiv1/trials/json?token=SomeHardKey&player_id=1,2,3,4
¶ API Full Query Example
Here is an example of a complete API Query.
https://api.kinatrax.com/apiv1/trials/gather.json?token=aLongKey&created_after=02-02-2020&limit=10
This will return 10 JSON data objects that were created after Feb 2nd 2020.
¶ API Advanced Metric Searching
The API allows users to perform advanced searches on metric values by constructing search parameters. Search parameters can be chained together by separating values with commas, as well as using key terms/options. Search queries keys and structure must match exactly to return the expected results. Raw SQL in the URL is not accepted, and may result in users being locked out.
Search parameter keys:
query_metric Required. (Assign the metric name + search logic)
join_type Optional. (Assign to “and” to use). By default queries are joined by OR, but enabling this will join searching with AND. Using AND requires all search parameters to match to return data.
Here are the comparing logic options:
[grt] Greater than.
[gre] Greater than or Equal to.
[lsl] Less than.
[lse] Less than or Equal to.
[eql] Equal to.
[neq] Not Equal to.
Here are the inner chaining logic options:
[and] And.
[ors] Or.
¶ Query Structure
Search parameter key
query_metric=
Then metric search value
query_metric=Pitch_type
Then compare operator
query_metric=Pitch_type[eql]
Than the value to compare to.
query_metric=Pitch_type[eql]Four-seam FB
Optional. Inner chaining searches.
query_metric=Pitch_type[eql]Four-seam FB[ors]Pitch_type[eql]Fast Ball
query_metric=Pitch_type[eql]Four-seam FB[and]Pitch_type[eql]Fast Ball
Optional. Outer chaining searches on AND.
query_metric=Pitch_type[eql]Four-seam FB[and]Pitch_type[eql]Fast Ball,Elbow_Varus_Torque[grt]100&join_type=and
¶ Example
This Example will returns data where (Pitch_Type = Four-seam FB) or (Elbow_Angle_FS > 92.37558) or (Elbow_Varus_Torque > 100 or Elbow_Varus_Torque < 150)
/apiv1/trials/json?token=SomeHardKey&query_metric=Pitch_Type[eql]Four-seam FB,Elbow_Angle_FS[grt]92.37558,Elbow_Varus_Torque[grt]100[ors]Elbow_Varus_Torque[lsl]150
This Example will returns data where (Pitch_Type = Four-seam FB) and (Elbow_Angle_FS > 92.37558) and (Elbow_Varus_Torque >100 or Elbow_Varus_Torque < 150)
/apiv1/trials/json?token=SomeHardKey&query_metric=Pitch_Type[eql]Four-seam FB,Elbow_Angle_FS[grt]92.37558,Elbow_Varus_Torque[grt]100[ors]Elbow_Varus_Torque[lsl]150&join_type=and
¶ Upload Tool
This tool is used to automate the importing of Trial data.
¶ Add API URL
Use the service URL field to input the API address.
For the standard Kinatrax install the URL will be:
https://api.kinatrax.com/
¶ Set API Token
A token is required to upload data to the API. As an admin create a API Key in connections, then add this key here.
The show token option will make the API Key visible.
The Persist option will save the token to you local disk for future uploads. If you do not allow the token to persist you will have to enter it every time.
¶ Selecting Upload Directory
Use the Scan Directory field to choose where the Trial data to upload is located.
¶ Limit Upload
Adding a value here will make the program stop after uploading the selected number of Trials.
¶ Delay Between Uploads
This option allows users to set a pause between uploads. This is useful for not overloading the API server.
¶ Overwrite Uploaded Data
The tool has the ability to re-upload a Trial and overwrite the existing data. Use the toggle to enable this feature.
¶ Ignore Upload Failures
In some cases it might be useful for the upload tool to continue to upload even if there was an error during a file upload. To ignore failures, toggle the ignore failures switch to on.
¶ Ignore Invalid SSL
Self signed or expired SSL certificates on the API will cause issues with uploading. To disable verifying the SSL certificate toggle the ignore SSL switch to on.
¶ Quick Scan
To disable the built in timestamp check and improve directory scanning speed toggle the quick scan switch to on.
¶ Clear Previous Uploaded
To clear out the cache of files that have been previously upload press the Reset File Cache button. This is useful for re-uploading existing data that has not been updated.
¶ Begin Automated Upload
When all the required fields have been entered click start scan to being the upload routine. While the program is uploading the log will display its status inside the text box of the application.
¶ Download the Tool
You can download the tool here.
¶ Status Codes
In some occasions EZ-Trax may return status or error codes. Below is what each code means. Error messages received from the API will be explained in the EZ-Trax UI.
0 --- Request successful.
2 --- Request failed while connecting.
3 --- Request failed while resolving.
4 --- Request failed due to connection (read/write) error.
5 --- Request failed on SSL handshake.
6 --- Request does not have a response (yet).
7 --- Request exceeded its maximum size limit
8 --- Request failed (currently unused).
9 --- Request couldn't open the download file.
10 --- Request couldn't write to the download file.
11 --- Request reached its maximum redirect limit
12 --- Request results timed out.
¶ Error Alerts
The upload tool keeps track of all error alerts during runtime. To view these alerts, click on the bell icon to display the list of the files that had errors.
