Package 'YTAnalytics'

Title: Wrapper for 'YouTube Analytics' API
Description: Simplify working with the 'YouTube Analytics' API <https://developers.google.com/youtube/analytics>. Collect data for your channel including geography, traffic sources, time period, etc.
Authors: Jake Davis [aut, cre, cph]
Maintainer: Jake Davis <[email protected]>
License: MIT + file LICENSE
Version: 0.2.0
Built: 2025-02-19 05:29:20 UTC
Source: https://github.com/davisj95/ytanalytics

Help Index

Analytics Request Function - YouTube Analytics API

Description

This is the function to make API calls to the YouTube Analytics API. Most other functions in this package are wrappers for this function with some arguments already populated. If none of the other prebuilt functions work for your use case, this is the function to turn to.

Usage

analytics_request(
  dimensions = NULL,
  metrics = "views,estimatedMinutesWatched",
  sort = NULL,
  maxResults = 10,
  filters = NULL,
  startDate = "2000-01-01",
  endDate = as.character(Sys.Date()),
  ids = "channel==MINE",
  currency = NULL,
  startIndex = NULL,
  includeHistoricalChannelData = NULL,
  token = getOption("YouTube_Token")
)

Arguments

dimensions

String. See https://developers.google.com/youtube/analytics/dimensions for valid arguments.
metrics

String. See https://developers.google.com/youtube/analytics/metrics for valid arguments.
sort

String. Specify by which metric/dimensions to sort output if applicable.
maxResults

Integer. Specify the number of results to return. Maximum is 200.
filters

String. Specify dimension to filter on if applicable. Ex: video==dQw4w9WgXcQ
startDate

Required. String specifying start date.
endDate

Required. String specifying end date.
ids

Required. Specify the channel. By default the function will specify "channel==MINE"
currency

String. Specify currency if applicable
startIndex

Integer. Specify index of first entity to retrieve, if applicable.
includeHistoricalChannelData

String. Indicates whether the API response should include channels' watch time and view data from the time period prior to when the channels were linked to the content owner. Only applies to content owner reports. Either 'true' or 'false'.
token

Required.

Value

data.frame

Examples

## Not run: 
analytics_request(startDate = "2018-05-01", 
                  endDate = "2017-01-01", 
                  metrics = "views,comments,likes,dislikes,estimatedMinutesWatched")

## End(Not run)

Channel City Data

Description

Returns top cities by views. Data is only available after January 1, 2022.

Usage

channel_cities(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_cities()

## End(Not run)

Channel Country Data

Description

Returns top countries by views

Usage

channel_countries(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_countries()

## End(Not run)

Channel Demographic Data

Description

Returns age and gender demographics

Usage

channel_demographics(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_demographics()

## End(Not run)

Channel Device Data

Description

Returns top devices by views

Usage

channel_devices(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_devices()

## End(Not run)

Channel Live & OnDemand Data

Description

Return channel data split by live & on demand.

Usage

channel_live_onDemand(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame()

Examples

## Not run: 
channel_live_onDemand()

## End(Not run)

Channel Playback Location

Description

Returns the type of page or application where video playbacks occurred.

Usage

channel_playback_location(...)

Arguments

...

Addt. arguments passed to analytics_request

Details

For more information, refer to https://developers.google.com/youtube/analytics/dimensions#Playback_Location_Dimensions

Value

data.frame

Examples

## Not run: 
channel_playlist_location()

## End(Not run)

Channel Playlists

Description

Returns all playlists in channel.

Usage

channel_playlists(...)

Arguments

...

Addt. arguments passed to data_playlist_request

Value

data.frame

Examples

## Not run: 
channel_playlists()

## End(Not run)

Channel Sharing Services Data

Description

Returns top sharing services by views

Usage

channel_sharing_services(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_sharing_services()

## End(Not run)

Channel Statistics

Description

#' @description Returns high level video stats.

Usage

channel_stats(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_stats()

## End(Not run)

Channel Subscription Status

Description

#' @description Returns the subscription status of channel views.

Usage

channel_subscription_status(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_subscription_status()

## End(Not run)

Channel Time Period Views

Description

Returns channel views by day or month.

Usage

channel_time_period(
  period = "day",
  endDate = as.character(format(Sys.Date(), "%Y-%m-01")),
  ...
)

Arguments

period

Required. Time period to breakdown data by. Supported values are day and month
endDate

Required. String. Data returned up until the last day specified, so for monthly period the end date must end with a day of 01
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_time_period()

## End(Not run)

Channel Top Videos

Description

Returns top videos by views

Usage

channel_top_videos(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_top_videos()

## End(Not run)

Channel Traffic Sources Data

Description

Returns top traffic sources by views. Check out https://developers.google.com/youtube/analytics/dimensions#Traffic_Source_Dimensions for more information.

Usage

channel_traffic_details(trafficType = "EXT_URL", ...)

Arguments

trafficType

Required. String. Type of traffic source.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_traffic_sources()

## End(Not run)

Channel Traffic Sources Data

Description

Returns top traffic sources by views

Usage

channel_traffic_sources(...)

Arguments

...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
channel_traffic_sources()

## End(Not run)

Channel Videos List

Description

Returns all videos in channel. Note: As of July 2023, the YouTube Data API fails to return ALL videos on a channel by getting all videos from the "uploads" playlist for large YouTube channels. As a result this function's work-around is to pull all additional playlists from the channel, pull all video lists from all playlists, and append the result to the uploads return.

Usage

channel_videos(token = getOption("YouTube_Token"))

Arguments

token

YouTube token

Value

data.frame

Examples

## Not run: 
channel_videos()

## End(Not run)

Channel Data Requests - YouTube Data API

Description

This is a function to make API calls to the YouTube Data API for channel specific data. While it can be called directly, it is primarily intended to help get lists of videos within a channel. For more in-depth use of the Data API, please refer to tuber. For more details on the following arguments, please refer to https://developers.google.com/youtube/v3/docs/channels/list

Usage

data_channel_request(
  part = NULL,
  categoryId = NULL,
  forUsername = NULL,
  hl = NULL,
  id = NULL,
  managedByMe = NULL,
  maxResults = 5,
  mine = NULL,
  onBehalfOfContentOwner = NULL,
  pageToken = NULL,
  token = getOption("YouTube_Token")
)

Arguments

part

Required. String.
categoryId

String.
forUsername

String.
hl

String.
id

String.
managedByMe

String.
maxResults

Integer.
mine

String.
onBehalfOfContentOwner

String.
pageToken

String.
token

Required.

Value

data.frame

Examples

## Not run: 
data_channel_request(part = "contentDetails",
                     mine = "true")

## End(Not run)

Playlist Data Requests - YouTube Data API

Description

This is a function to make API calls to the YouTube Data API for playlist specific data. While it can be called directly, it is primarily intended to help get lists of videos within a playlist. For more in-depth use of the Data API, please refer to tuber. For more details on the following arguments, please refer to https://developers.google.com/youtube/v3/docs/playlists/list

Usage

data_playlist_request(
  part = NULL,
  channelId = NULL,
  hl = NULL,
  id = NULL,
  maxResults = 5,
  mine = NULL,
  onBehalfOfContentOwner = NULL,
  onBehalfOfContentOwnerChannel = NULL,
  pageToken = NULL,
  token = getOption("YouTube_Token")
)

Arguments

part

Required. String.
channelId

String.
hl

String.
id

String.
maxResults

Integer.
mine

String
onBehalfOfContentOwner

String.
onBehalfOfContentOwnerChannel

String.
pageToken

String.
token

Required.

Value

data.frame

Examples

## Not run: 
data_playlist_request(part = "contentDetails",
                      id = "PLA2387dsgkhfs9832hjkhuihsASDF",
                      mine = "true")

## End(Not run)

Playlist Item Data Requests - YouTube Data API

Description

This is a function to make API calls to the YouTube Data API for playlist item data. While it can be called directly, it is primarily intended to help get lists of videos within a playlist. For more in-depth use of the Data API, please refer to tuber. For more details on the following arguments, please refer to https://developers.google.com/youtube/v3/docs/playlistItems/list

Usage

data_playlistItem_request(
  part = NULL,
  id = NULL,
  maxResults = 5,
  onBehalfOfContentOwner = NULL,
  pageToken = NULL,
  playlistId = NULL,
  videoId = NULL,
  token = getOption("YouTube_Token")
)

Arguments

part

Required. String.
id

String.
maxResults

Integer.
onBehalfOfContentOwner

String.
pageToken

String.
playlistId

String.
videoId

String.
token

Required.

Value

data.frame

Examples

## Not run: 
data_playlistItem_request(part = "contentDetails",
                          id = "PLA2387dsgkhfs9832hjkhuihsASDF",
                          mine = "true")

## End(Not run)

Video Data Requests - YouTube Data API

Description

This is a function to make API calls to the YouTube Data API for video data. While it can be called directly, it is primarily inteded to help get metadata about videos such as title or description. For more in-depth use of the Data API, please refer to tuber. For more details on the following arguments, please refer to https://developers.google.com/youtube/v3/docs/videos/list

Usage

data_video_request(
  part = NULL,
  chart = NULL,
  hl = NULL,
  id = NULL,
  locale = NULL,
  maxHeight = NULL,
  maxResults = NULL,
  maxWidth = NULL,
  myRating = NULL,
  onBehalfOfContentOwner = NULL,
  pageToken = NULL,
  regionCode = NULL,
  videoCategoryId = NULL,
  token = getOption("YouTube_Token")
)

Arguments

part

Required. String
chart

String.
hl

String.
id

String.
locale

String.
maxHeight

Integer.
maxResults

Integer.
maxWidth

Integer.
myRating

String.
onBehalfOfContentOwner

String.
pageToken

String.
regionCode

String.
videoCategoryId

String.
token

Required.

Value

data.frame()

Examples

## Not run: 
data_video_request(part = "contentDetails",
                          id = "dQw4w9WgXcQ")

## End(Not run)

Playlist Country Data

Description

Returns top countries by views

Usage

playlist_countries(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_countries(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Demographic Data

Description

Returns age and gender demographics

Usage

playlist_demographics(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_demographics(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Device Data

Description

Returns top devices by views

Usage

playlist_devices(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_devices(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Live & OnDemand Data

Description

Return playlist data split by live & on demand.

Usage

playlist_live_onDemand(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_live_onDemand(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Metadata

Description

Playlist Metadata

Usage

playlist_metadata(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube Video.
...

Addt. arguments passed to data_video_request

Value

data.frame

Examples

## Not run: 
playlist_metadata(playlistId = "dQw4w9WgXcQ")

## End(Not run)

Playlist Playback Location

Description

Returns the type of page or application where video playbacks occurred.

Usage

playlist_playback_location(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Details

For more information, refer to https://developers.google.com/youtube/analytics/dimensions#Playback_Location_Dimensions

Value

data.frame

Examples

## Not run: 
playlist_playback_location(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Statistics

Description

#' @description Returns high level video stats.

Usage

playlist_stats(playlistId = NULL, ...)

Arguments

playlistId

Required. Strings. Id of YouTube Playlist
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_stats(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Subscription Status

Description

#' @description Returns the subscription status of playlist views.

Usage

playlist_subscription_status(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube Playlist
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_subscription_status(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Top Videos

Description

Returns top videos by views.

Usage

playlist_top_videos(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_top_videos(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Traffic Sources Data

Description

Returns top traffic sources by views. Check out https://developers.google.com/youtube/analytics/dimensions#Traffic_Source_Dimensions for more information.

Usage

playlist_traffic_details(playlistId = NULL, trafficType = "EXT_URL", ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
trafficType

Required. String. Type of traffic source.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_traffic_sources(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Traffic Sources Data

Description

Returns top traffic sources by views

Usage

playlist_traffic_sources(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_traffic_sources(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Playlist Videos List

Description

Returns all videos in playlist

Usage

playlist_videos(playlistId = NULL, ...)

Arguments

playlistId

Required. String. Id of YouTube playlist.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
playlist_videos(playlistId = "PL2MI040U_GXq1L5JUxNOulWCyXn-7QyZK")

## End(Not run)

Video Audience Retention

Description

Returns audience retention percentages for a video. By default this function will return audience retention rates for organic views.

Usage

video_audience_retention(videoId = NULL, audienceType = "ORGANIC", ...)

Arguments

videoId

Required. String. Id of YouTube video.
audienceType

Required. String. Supported values are ORGANIC, AD_INSTREAM, and AD_INDISPLAY
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_audience_retention(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video City Data

Description

Returns top cities by views. Data is only available after January 1, 2022.

Usage

video_cities(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_cities(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Country Data

Description

Returns top countries by views

Usage

video_countries(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_countries(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Demographic Data

Description

Returns age and gender demographics

Usage

video_demographics(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_demographics(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Device Data

Description

Returns top devices by views

Usage

video_devices(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_devices(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Live & OnDemand Data

Description

Return video data split by live & on demand.

Usage

video_live_onDemand(videoId = NULL, ...)

Arguments

videoId

Required.String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_live_onDemand(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Metadata

Description

Video Metadata

Usage

video_metadata(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube Video.
...

Addt. arguments passed to data_video_request

Value

data.frame

Examples

## Not run: 
video_metadata(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Playback Location

Description

Returns the type of page or application where video playbacks occurred.

Usage

video_playback_location(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Details

For more information, refer to https://developers.google.com/youtube/analytics/dimensions#Playback_Location_Dimensions

Value

data.frame

Examples

## Not run: 
video_playback_location(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Sharing Services Data

Description

Returns top sharing services by views

Usage

video_sharing_services(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_sharing_services(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Statistics

Description

Returns high level video stats.

Usage

video_stats(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_stats(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Subscription Status

Description

Returns the subscription status of video views.

Usage

video_subscription_status(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_subscription_status(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Time Period Views

Description

Returns video views by day or month.

Usage

video_time_period(
  videoId = NULL,
  period = "day",
  endDate = as.character(format(Sys.Date(), "%Y-%m-01")),
  ...
)

Arguments

videoId

Required. String. Id of YouTube video.
period

Required. Time period to breakdown data by. Supported values are day and month
endDate

Required. String. Data returned up until the last day specified, so for monthly period the end date must end with a day of 01
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_time_period(videoId = "dQw4w9WgXcQ", period = "month")

## End(Not run)

Video Traffic Details Data

Description

Returns traffic details by views. Check out https://developers.google.com/youtube/analytics/dimensions#Traffic_Source_Dimensions for more information.

Usage

video_traffic_details(videoId = NULL, trafficType = "EXT_URL", ...)

Arguments

videoId

Required. String. Id of YouTube video.
trafficType

Required. String. Type of traffic source.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_traffic_sources(videoId = "dQw4w9WgXcQ")

## End(Not run)

Video Traffic Sources Data

Description

Returns top traffic sources by views

Usage

video_traffic_sources(videoId = NULL, ...)

Arguments

videoId

Required. String. Id of YouTube video.
...

Addt. arguments passed to analytics_request

Value

data.frame

Examples

## Not run: 
video_traffic_sources(videoId = "dQw4w9WgXcQ")

## End(Not run)

YouTube API OAuth

Description

This creates or grabs a token to authorize API requests

Usage

youtube_oauth(
  clientId = NULL,
  clientSecret = NULL,
  tokenFile = ".httr-oauth",
  useOOB = FALSE,
  setEnvVar = FALSE,
  scopes = c("https://www.googleapis.com/auth/youtube.readonly",
    "https://www.googleapis.com/auth/yt-analytics.readonly"),
  reAuthOnFail = FALSE
)

Arguments

clientId

Required. Client Id obtained from console.cloud.google.com.
clientSecret

Required. Client Secret obtained from console.cloud.google.com
tokenFile

The name of the token httr-oauth file to read the token from. If the file does not exist then one will be created with the provided name.
useOOB

If TRUE, use oob method to copy/paste token into R.
setEnvVar

If TRUE, create an environment variable called "YouTube_Token" to store token.
scopes

Scopes that must be passed when authenticating. See https://developers.google.com/youtube/analytics/reference for more information.
reAuthOnFail

If TRUE, will automatically begin authentication process if provided token is expired.

Value

token environment

Examples

## Not run: 
youtube_oauth("123456789asdalksdjfhaslkdjfb.apps.googleusercontent.com",
              "MasdfH5320208ladshf790",
              token = ".httr-oauth-myToken")

## End(Not run)