API Documentation (using R)

Getting Started

Username: This is the email address associated with your TruMedia account.

Sitename: This is the name of your site. This is typically the first part of the URL of your site without the sport suffix (ex: sitename of cowboys-nfl.trumedianetworks.com is cowboys).

Temporary Token:

Temporary authentication tokens allow a URL to be authorized and accessed without login. In order to create a temporary token, a master token is required. The master token should remain private. Only the temporary token is exposed in the URL. Temporary authentication tokens will last for 24 hours by default, but can be requested to last for any duration up to 72 hours.

The two primary use cases for temporary authentication tokens are:

To implement an SSO integration allowing users of your internal site to access the TruMedia site without being required to log in separately.
To access the TruMedia APIs

Master Token:

These are currently provided by TruMedia. In a future release, they will be generated and managed within the TruMedia application by team Super Users. Using your Username, Sitename, and Master Token, you can use the code below to create a Temporary Token:

Code Template - Paste In Your Username, Sitename, and Master Token (for R):

CODE

#Downloading packages
require(curl)
require(httr)
require(dplyr)
#Generating token
headers <- c('Content-Type' = 'application/json')
data <- '{"username":"user@email.com", "sitename":"sitename", "token":"master token"}'
res <- httr::POST(url = 'https://api.trumedianetworks.com/v1/siteadmin/api/createTempPBToken', httr::add_headers(.headers=headers), body = data)
token <- content(res)
tok <- token$pbTempToken

Pulling Data

A user can pull data by editing parts of the query URL. Below is the URL:

data <- read.csv(paste(“https://api.trumedianetworks.com/v1/nflapi/customQuery/dataFormat.csv?”, “param1”, param1, “&param2=”, param2, “&columns=”, columns, filters, qualifications, sort, “&token=”, tok, sep = ““)

Adjusting Data Format

This will adjust the format that the data is presented, changing what each row represents, The options for dataFormat are TeamTotals, TeamSeasons, TeamGames, TeamDrives, TeamPlays, PlayerTotals, PlayerSeasons, PlayerGames, and PlayerPlays. You can also change the file type to JSON or CSV.

Adding Parameters

This can narrow the dataset to only what you want to see. In order to add parameters, you will need to declare the parameter and its settings before the query URL. In the query URL, you will need to add the parameter and its contents into the URL. To see all available parameters, please see the list below:

seasonYear: Satisfies requirement for all team queries and player queries.
- For single years:

CODE

seasonYear <- 2023

For multiple years:

CODE

seasonYear <- “2021%2C2022%2C2023”

seasonType: Comma delimited list of season type IDs.
week: Comma delimited list of week numbers.
game: Satisfies requirement for all queries. Comma delimited list of game IDs. Max of 50 game ID’s for team and player queries.
eliasGame: Satisfies requirement for all queries. Comma delimited list of Elias game IDs. Max of 50 game ID’s for team and player queries.
gsisGame: Satisfies requirement for all queries. Comma delimited list of GSIS game keys. Max of 50 game ID’s for team and player queries.
ngsGame: Satisfies requirement for all queries. Comma delimited list of NGS game IDs. Max of 50 game ID’s for team and player queries.
team: Comma delimited list of up to 10 team IDs (except for player queries which take only 1 team ID). Satisfies requirement for all team and player queries.
eliasTeam: Comma delimited list of up to 10 Elias team IDs (except for player queries which take only 1 team ID). Satisfies requirement for all team and player queries.
Player: Comma delimited list of up to 10 player IDs. Satisfies requirement for all player queries.
eliasPlayer: Comma delimited list of up to 10 Elias player IDs. Satisfies requirement for all player queries.
gsisPlayer: Comma delimited list of up to 10 GSIS player IDs. Satisfies requirement for all player queries.
ngsPlayer: Comma delimited list of up to 10 NGS player IDs. Satisfies requirement for all player queries.
statEvent: Required for the Team Plays and Player Plays query, this defines the stat for events being queried. This parameter is essentially like clicking on a stat in the UI to get the events that relate to that stat. See the example no. 3 in the Query Examples at the bottom of this page.
Format: FORMATTED - formatted value (ex: ‘.123’, ‘12%’, etc.); RAW - raw decimal values; MIXED - For JSON only, an array with both the formatted and raw values.

Note: For every additional parameter, you will need to include an ampersand (“&”) when listing them in the query URL.

Example: “seasonYear”, seasonYear, “&seasonType=”, seasonType, “&week=”, week,…

Adding Columns

Using the native stat abbreviations, you can list the columns you want to pull in this format:

CODE

columns <- “[stat1],[stat2]”

To see all available stats, please visit this document.

Note: Make sure to use brackets around stat abbreviations and do not leave any spaces in column listing.

Example:

CODE

columns <- “[Rush],[RshYds],[RshTD]”

Adding Filters

To add filters to your query URL, you can use this helpful tool by visiting this tool. Put your site URL prefix into the red italicized section below: https://insert_your_site_url_here.trumedianetworks.com/football/tools?pd=%7B"activeTab"%3A"queryTool"%7D

Once one this page, click on the ‘Search Filters’ dropdown and search for the desired filters. Once complete, click on the ‘Show Where Clause’ button and copy the text from the second section into your filter declaration statement

Example:

CODE

filters <- “&filters=(((event.passRushersCount%20%3E%3D%205)))”)

Adding Qualifications

Optional qualification clause for limiting results. Applies to all queries except Plays queries. This parameter is essentially like using the Qualifications UI control on a player or team page. The URL string is:

qualifications <- “qualification=%5Bstat1%5D+%3D+number”

For example, if you wanted to set a qualification for the query results to only include players with 500 or more attempts, you would use the following as your qualifications declaration statement (printed before the query):

qualifications <- “qualification=%5BAtt%5D+%3D+500”

Note: Qualifications will be applied before filters in the query statement. For example, if a user builds a query to find all red zone passing production among quarterbacks with 500+ attempts, the 500+ attempt qualification will be implemented first (narrowing the query to players with 500+ total attempts) and the passing production with the applied filters will follow.

Adding Sort

Optional order clause for sorting the results. This parameter is essentially like clicking on a stat column header in the UI to sort the report by that stat. The URL string is:

sort <- “&sort=%5Bstat1%5D+ORDER”

For example, if you wanted to to sort the query results by passing attempts descending, you would use the following as your qualifications declaration statement (printed before the query):

sort <- “&sort=%5BAtt%5D+DESC”

Data Query Examples

Below is an example pulling passing stats by team season against the blitz in the 2023 regular season among players with at least 500 total attempts sorted by passer rating descending:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the 2023 Regular Season
seasonYear <- 2023
seasonType <- "REG"
#Setting the columns for basic passing stats
columns <- “[Att],[PsYds],[PsTD],[PsrRt]”
#Adding filter for blitz (copied from results from filter URL generation process)
filters <- “&filters=(((event.passRushersCount%20%3E%3D%205)))”
#Adding qualification for players with at least 500 attempts
qualifications <- “&qualification=%5BAtt%5D+%3E%3D+500”
#Adding sort for passer rating descending 
sort <- “&sort=%5BPsrRt%5D+DESC”
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/TeamSeasons.csv?", "seasonYear=", seasonYear, "&seasonType=", seasonType, "&columns=", columns, filters, qualifications, sort, "&token=", tok, sep = ""))
head(data, 5)

Below is an example of pulling rushing stats from team plays in the 2022 regular season and playoffs that were rushing plays in shotgun formation that took place in the red zone against heavy boxes (8+ defenders) sorted by Rush EPA descending:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the 2022 Regular Season & Playoffs
seasonYear <- 2022
seasonType <- "REG,PLY"
#Setting the columns
columns <- "[RusherName|EVENT],[RusherID|EVENT],[PlayDesc|EVENT],[RshYds],[OffRushEPA]"
#Adding filter for shotgun formation, heavy boxes, and redzone (copied from results from filter URL generation process)
filters <- “&filters=(((event.playFromShotgun))%20AND%20(team.event.goalDistStart%20%3C%3D%2019)%20AND%20(event.playType%20IN%20('RUSH'))%20AND%20(event.boxCount%20%3E%3D%208))”
#Adding statEvent to satisfy TeamPlays query
statEvent <- “[Snaps]”
#Adding sort for passer rating descending 
sort <- "&sort=%5BOffRushEPA%5D+DESC"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/TeamPlays.csv?", "seasonYear=", seasonYear, "&seasonType=", seasonType, “&columns=", columns, filters, sort, "&statEvent=", statEvent, "&token=", tok, sep = ""))
head(data, 5)

Below is an example of pulling all team touchdown plays in the 2023 regular season:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the 2023 Regular Season
seasonYear <- "2023"
seasonType <- "REG"
#Adding statEvent to satisfy TeamPlays query
statEvent <- "[TD]"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/TeamPlays.csv?", "seasonYear=", seasonYear, "&seasonType=", seasonType, "&statEvent=", statEvent,"&token=", tok, sep = ""))
head(data, 5)

Below is an example of pulling passing stats by game for Patrick Mahomes (regular season only):

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the Regular Season Patrick Mahomes
seasonType <- "REG"
player <- 33873
#Setting the columns
columns <- "[Drpbk],[Att],[Comp],[PsTD],[Int]"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/PlayerGames.csv?", "seasonType=", seasonType, "&player=", player, "&columns=", columns, "&token=", tok, sep = ""))
head(data,5)

Below is an example of pulling team aggregated basic passing stats (raw numeric values) for home games only during the 2023 regular season sorted by passer rating descending:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the 2023 Regular Season
seasonYear <- 2023
seasonType <- "REG"
#Setting the columns
columns <- "[Drpbk],[Cmp],[Att],[PsYds],[Comp%],[PsTD],[Int],[PsrRt]"
#Adding filter for home games (copied from results from filter URL generation process)
filters <- "&filters=(((team.game.home%20AND%20NOT%20game.neutralSite)))"
#Adding sort for passer rating descending
sort <- "&sort=%5BPsrRt%5D+DESC"
#Adding format parameter to retrieve raw figures
format <- "RAW"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/TeamTotals.csv?", "seasonYear=", seasonYear, "&seasonType=", seasonType, "&columns=", columns, filters, sort, "&format=", format, "&token=", tok, sep = ""))
head(data,5)

Below is an example of pulling all Kansas City team drives in the 2021-2023 regular seasons having 10 or more plays:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the 2021-2023 Regular Season Kansas City
seasonYear <- "2021%2C2022%2C2023"
seasonType <- "REG"
team <- 2310
#Adding filter for drives with 10+ plays (copied from results from filter URL generation process)
filters <- "&filters=((team.event.drivePlays%20%3E%3D%2010))"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/TeamDrives.csv?", "seasonYear=", seasonYear, "&seasonType=", seasonType, "&team=", team, filters,"&token=", tok, sep = ""))
head(data,5)

Below is an example of pulling player total defensive stats for 2023 regular season Kansas City players with 10 or more defensive snaps sorted by defensive snaps descending:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the 2023 Regular Season Kansas City Chiefs
seasonYear <- 2023
seasonType <- "REG"
team <- 2310
#Setting the columns
columns <- "[DfSnap],[DfTkl],[DSk],[DInt]"
#Adding qualification for players with at least 10 defensive snaps
qualifications <- "&qualification=%5BDfSnap%5D+%3E%3D+10"
#Adding sort for defensive snaps descending 
sort <- "&sort=%5BDfSnap%5D+DESC"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/PlayerTotals.csv?", "seasonYear=", seasonYear, "&seasonType=", seasonType, "&team=", team, "&columns=", columns, qualifications, sort, "&token=", tok, sep = ""))
head(data,5)

Below is an example of pulling player season regular season receiving stats for New England players with more than 500 receiving yards since 2004:

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Setting parameters for the Regular Season New England Patriots
seasonType <- "REG"
team <- 3200
#Setting the columns
columns <- "[Tar],[Rec],[RecYds],[RecTD]"
#Adding filter for drives with 10+ plays (copied from results from filter URL generation process)
filters <- "&filters=((season.seasonYear%20%3E%3D%202004))"
#Adding qualification for players with at least 500 receiving yards
qualifications <- "&qualification=%5BRecYds%5D+%3E%3D+500"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/customQuery/PlayerSeasons.csv?", "seasonType=", seasonType, "&team=", team, "&columns=", columns, qualifications, filters, "&token=", tok, sep = ""))
head(data,5)

Pulling Video

(The VideoLinker api only works for NCAA data.)

A user can pull data by editing parts of the query URL. Below is the URL:

https://api.trumedianetworks.com/v1/nflapi/videoLinker.csv?playlist=gameID1:playID1,gameID2:playID2,...&level=level&token=token

Required Parameters

Format: This can be set to csv or json.
GameID: GSIS Game Key or Elias Game ID
PlayID: GSIS play ID
- Note: You can add up to 50 gameID-playID combinations per call
Token: See the Getting Started section in order to generate tokens.

Optional Parameters

Level: This can be set to NFL or NCAA. If left off, the level defaults to NFL

Authentication:
All video URLs returned are authenticated with AWS for 24 hours. After 24 hours you can no longer download or view the videos without making a new call to the API and getting an updated URL for the videos

Video Query Example

CODE

#Authentification
##Copy and paste code from the Getting Started section
#Set Parameters
playlist <- "59171:56"
level <- "nfl"
#Query Statement
data <- read.csv(paste("https://api.trumedianetworks.com/v1/nflapi/videoLinker.csv?", "playlist=", playlist, "&level=", level, "&token=", tok, sep = ""))
head(data,5)