--- title: "tubern: Comprehensive YouTube Analytics Examples" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{tubern: Comprehensive YouTube Analytics Examples} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = FALSE ) ``` # tubern: Enhanced YouTube Analytics for R This vignette demonstrates the enhanced features of tubern, showing you how to efficiently retrieve, analyze, and visualize YouTube Analytics data. ## Quick Setup ```{r setup} library(tubern) # First-time setup - shows setup guide yt_oauth() # Or with your credentials yt_oauth("your-client-id.apps.googleusercontent.com", "your-client-secret") ``` ## New Features Overview ### 1. Relative Date Ranges No more manual date calculations! Use intuitive relative dates: ```{r dates} # Get common date range options get_common_date_ranges() # Use relative dates in reports report <- get_report( ids = "channel==MINE", metrics = "views,likes", start_date = "last_30_days" # End date calculated automatically ) # More examples get_report(ids = "channel==MINE", metrics = "views", start_date = "this_month") get_report(ids = "channel==MINE", metrics = "views", start_date = "last_quarter") get_report(ids = "channel==MINE", metrics = "views", start_date = "yesterday") ``` ### 2. Helper Functions for Common Reports #### Channel Overview ```{r channel_overview} # Get comprehensive channel performance overview <- get_channel_overview("last_30_days") # Customize what metrics to include overview <- get_channel_overview( "this_month", include_engagement = TRUE, include_subscribers = TRUE ) ``` #### Top Performing Videos ```{r top_videos} # Get top 10 videos by views top_videos <- get_top_videos("last_7_days") # Get more videos with custom metrics top_videos <- get_top_videos( "last_30_days", max_results = 25, metrics = c("views", "likes", "comments", "shares", "estimatedMinutesWatched") ) ``` #### Audience Demographics ```{r demographics} # Full demographic breakdown demographics <- get_audience_demographics("last_90_days") # Age groups only age_data <- get_audience_demographics("this_month", dimension = "ageGroup") # Gender breakdown only gender_data <- get_audience_demographics("this_quarter", dimension = "gender") ``` #### Geographic Performance ```{r geographic} # Top countries by views geo_performance <- get_geographic_performance("last_30_days") # US states/provinces (requires filtering to US) us_states <- get_geographic_performance( "this_month", dimension = "province", filters = "country==US" ) ``` #### Device and Platform Analysis ```{r devices} # Performance by device type - use get_report directly device_performance <- get_report( ids = "channel==MINE", metrics = "views,estimatedMinutesWatched", dimensions = "deviceType", start_date = "last_30_days" ) # Operating system breakdown os_performance <- get_report( ids = "channel==MINE", metrics = "views,estimatedMinutesWatched", dimensions = "operatingSystem", start_date = "this_month" ) # Both device and OS device_os <- get_report( ids = "channel==MINE", metrics = "views,estimatedMinutesWatched", dimensions = "deviceType,operatingSystem", start_date = "last_7_days" ) ``` #### Daily Time Series Data ```{r daily} # Daily performance trends daily_data <- get_daily_performance("last_30_days") # With engagement metrics daily_engagement <- get_daily_performance( "this_month", metrics = c("views", "likes", "comments", "shares") ) ``` #### Revenue Reports (Requires Monetary Scope) ```{r revenue} # Set up OAuth with monetary scope first yt_oauth("your-client-id", "your-client-secret", scope = "monetary") # Get revenue data revenue <- get_revenue_report("last_month") # Revenue in different currency revenue_eur <- get_revenue_report("this_quarter", currency = "EUR") ``` ### 3. Enhanced Parameter Validation tubern now provides helpful validation and suggestions: ```{r validation} # Invalid metrics get helpful suggestions # get_report(ids = "channel==MINE", metrics = "vews", start_date = "last_7_days") # Error: Invalid metric(s): vews # Did you mean: 'vews' -> 'views' # Check available metrics and dimensions get_available_metrics() get_available_metrics("view") # Filter by pattern get_available_dimensions() get_available_dimensions("country|city") # Geographic dimensions ``` ### 4. Data Transformation and Analysis #### Convert to Data Frames ```{r dataframes} # Get data and convert to clean data.frame report <- get_daily_performance("last_30_days") df <- yt_to_dataframe(report) head(df) # Convert to tibble (if tibble package installed) tbl <- yt_to_tibble(report) # Keep original column names df_orig <- yt_to_dataframe(report, clean_names = FALSE) ``` #### Data Export ```{r export} # Export to CSV report <- get_top_videos("last_7_days") file_path <- yt_export_csv(report, "top_videos.csv") # Auto-generated filename with timestamp file_path <- yt_export_csv(report) ``` #### Quick Visualization ```{r plots} # Automatic plot creation (requires ggplot2) daily_report <- get_daily_performance("last_30_days") yt_quick_plot(daily_report) # Line plot over time # Bar chart for top videos top_videos <- get_top_videos("last_7_days") yt_quick_plot(top_videos, chart_type = "bar") # Custom x and y columns geo_data <- get_geographic_performance("last_30_days") yt_quick_plot(geo_data, x_col = "country", y_col = "views") ``` #### Data Summary ```{r summary} # Get summary statistics report <- get_channel_overview("last_30_days") summary <- yt_extract_summary(report) print(summary) ``` ### 5. Improved Error Handling and Diagnostics #### Diagnostic Tools ```{r diagnostics} # Check if everything is set up correctly diagnose_tubern() # Check API quota status check_api_quota() ``` #### Error Recovery ```{r errors} # tubern now provides helpful error messages and suggestions # for authentication, API quota, parameter errors, etc. # Example: If OAuth token expires, tubern will suggest running yt_oauth() again # Example: If API quota is exceeded, tubern will suggest ways to reduce usage ``` ## Complete Workflow Examples ### Example 1: Channel Performance Dashboard ```{r workflow1} # Set up authentication yt_oauth("your-client-id", "your-client-secret") # Get overview data overview <- get_channel_overview("last_30_days") overview_df <- yt_to_dataframe(overview) # Get daily trends daily <- get_daily_performance("last_30_days") daily_df <- yt_to_dataframe(daily) # Get top videos top_videos <- get_top_videos("last_30_days", max_results = 10) videos_df <- yt_to_dataframe(top_videos) # Get geographic performance geo <- get_geographic_performance("last_30_days") geo_df <- yt_to_dataframe(geo) # Create visualizations yt_quick_plot(daily) # Daily trend yt_quick_plot(top_videos) # Top videos yt_quick_plot(geo) # Geographic performance # Export data yt_export_csv(overview, "channel_overview.csv") yt_export_csv(daily, "daily_performance.csv") yt_export_csv(top_videos, "top_videos.csv") ``` ### Example 2: Audience Analysis ```{r workflow2} # Demographic analysis demographics <- get_audience_demographics("last_90_days") demo_df <- yt_to_dataframe(demographics) # Device analysis devices <- get_report( ids = "channel==MINE", metrics = "views,estimatedMinutesWatched", dimensions = "deviceType", start_date = "last_90_days" ) device_df <- yt_to_dataframe(devices) # Geographic analysis geography <- get_geographic_performance("last_90_days", max_results = 50) geo_df <- yt_to_dataframe(geography) # Combined analysis with dplyr (if available) if (require(dplyr)) { # Top countries by watch time top_countries <- geo_df %>% arrange(desc(estimated_minutes_watched)) %>% head(10) print(top_countries) } ``` ### Example 3: Content Performance Analysis ```{r workflow3} # Analyze video performance over time videos_monthly <- get_top_videos("this_month", max_results = 50) videos_df <- yt_to_dataframe(videos_monthly) # Compare with previous month videos_prev <- get_top_videos("last_month", max_results = 50) videos_prev_df <- yt_to_dataframe(videos_prev) # Daily performance for trend analysis daily_trends <- get_daily_performance( "last_30_days", metrics = c("views", "estimatedMinutesWatched", "likes", "comments") ) trends_df <- yt_to_dataframe(daily_trends) # Visualize trends yt_quick_plot(daily_trends, x_col = "day", y_col = "views") ``` ## Best Practices ### 1. Authentication - Use `scope = "monetary"` only when you need revenue data - Keep your OAuth credentials secure - Use `diagnose_tubern()` to troubleshoot authentication issues ### 2. Data Retrieval - Use relative dates for convenience: `"last_30_days"`, `"this_month"` - Start with helper functions like `get_channel_overview()` before using `get_report()` directly - Use `max_results` parameter to limit data when testing ### 3. Error Handling - Always check `diagnose_tubern()` if you encounter issues - Use `check_api_quota()` to monitor your API usage - Enable `setup_guide = TRUE` for first-time setup help ### 4. Data Analysis - Convert API responses to data.frames with `yt_to_dataframe()` - Use `yt_quick_plot()` for rapid data exploration - Export data with `yt_export_csv()` for external analysis ## Troubleshooting ### Common Issues 1. **Authentication Problems** ```{r} # Run diagnostics diagnose_tubern() # Re-authenticate yt_oauth("your-client-id", "your-client-secret") ``` 2. **API Quota Exceeded** ```{r} # Check quota status check_api_quota() # Reduce data scope get_report(ids = "channel==MINE", metrics = "views", start_date = "yesterday", max_results = 10) ``` 3. **Invalid Parameters** ```{r} # Check available options get_available_metrics() get_available_dimensions() # Use helper functions for validation get_channel_overview("last_7_days") # Pre-validated parameters ``` ## More Resources - [YouTube Analytics API Documentation](https://developers.google.com/youtube/analytics) - [Google Cloud Console](https://console.cloud.google.com) for API setup - [tubern GitHub Repository](https://github.com/gojiplus/tubern) for issues and updates