Package {videogameinsightsR}

Video Game Insights Smart Cache System

Description

Provides intelligent caching for Steam App IDs and game metadata to minimize API calls while enabling local filtering by genre, platform, and other attributes.

Usage

.vgi_cache_dir()

Apply Rate Limiting to Date Sequence

Description

Simple function to add rate limiting to date-based loops

Usage

apply_rate_limit(
  date_position,
  total_dates,
  calls_per_batch = NULL,
  delay_seconds = NULL,
  show_messages = TRUE
)

Arguments

Value

No return value. Called for side effects (optional delay) and returns invisible(NULL).

Batch Processing Utilities

Description

Internal utilities for batching API requests to reduce stress on the API while maintaining performance and reliability.

Batched Data Fetching Functions

Description

Internal functions that add batching capabilities to existing date-based VGI functions to reduce API stress.

Create a Rate Limiter

Description

Creates a rate limiter object that tracks API calls and applies delays when thresholds are reached.

Usage

create_rate_limiter(
  calls_per_batch = 10,
  delay_seconds = 1,
  show_messages = TRUE
)

Arguments

Value

A rate limiter environment with increment() method

Examples

limiter <- create_rate_limiter(
  calls_per_batch = 5, delay_seconds = 0, show_messages = FALSE
)
for (i in 1:10) limiter$increment()
limiter$get_stats()

Get Steam App ID from Steam Store Search

Description

Searches the Steam store and returns the app ID of the first result. Useful for finding Steam IDs when you only know the game name.

Usage

get_steam_app_id(game_name)

Arguments

Value

Integer. The Steam App ID of the first search result, or NULL if not found.

Examples

## Not run: 
# Find Steam ID for a game
bf_id <- get_steam_app_id("Battlefield 2042 Open Beta")
print(bf_id)

## End(Not run)

Print Method for Year-over-Year Comparison

Description

Print Method for Year-over-Year Comparison

Usage

## S3 method for class 'vgi_yoy_comparison'
print(x, ...)

Arguments

Value

The input object x, invisibly.

Simple Rate Limiter for VGI API Calls

Description

Provides a simple counter-based rate limiter that can be used in existing loops to reduce API stress.

Check if Rate Limiting Should Be Applied

Description

Determines if rate limiting should be applied based on the expected number of API calls.

Usage

should_use_rate_limiting(num_dates, num_metrics = 1)

Arguments

Value

Logical indicating if rate limiting is recommended

Get Active Players Data by Date

Description

Retrieve daily and monthly active user (DAU/MAU) data for all games on a specific date, providing engagement metrics across the market.

Usage

vgi_active_players_by_date(
  date,
  steam_app_ids = NULL,
  offset = NULL,
  limit = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

Active player metrics provide deeper engagement insights than concurrent players:

• DAU: Unique players who launched the game on this date

• MAU: Unique players who launched the game in the past 30 days

• DAU/MAU ratio: Key metric for player retention (higher = better)

• Industry benchmark: 10-20\

These metrics are essential for:

• Measuring true player engagement

• Identifying games with strong retention

• Tracking seasonal patterns

• Comparing engagement across genres

• Forecasting player trends

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

dau

Integer. Daily active users

mau

Integer. Monthly active users

dauMauRatio

Numeric. DAU/MAU ratio (engagement rate)

activeRank

Integer. Rank by DAU

Examples

## Not run: 
# Get active player data
active_data <- vgi_active_players_by_date("2024-01-15")

# Top 20 games by DAU
top_dau <- head(active_data, 20)
cat("Top 20 games by daily active users:\n")
print(top_dau[, c("steamAppId", "dau", "mau", "dauMauRatio")])

# Find games with excellent retention (DAU/MAU > 25%)
high_retention <- active_data[active_data$dauMauRatio > 0.25 & 
                             active_data$dau > 1000, ]
cat("Games with >25% DAU/MAU ratio:", nrow(high_retention), "\n")
print(head(high_retention[order(-high_retention$dauMauRatio), ], 10))

# Compare with concurrent player data
ccu_data <- vgi_concurrent_players_by_date("2024-01-15")
engagement <- merge(active_data, ccu_data, by = "steamAppId")

# Calculate concurrent-to-DAU ratio (session intensity)
engagement$ccu_dau_ratio <- engagement$peakConcurrent / (engagement$dau + 1)

# Games with high session intensity (many concurrent per daily user)
high_intensity <- engagement[engagement$ccu_dau_ratio > 0.3 & 
                            engagement$dau > 1000, ]
cat("High session intensity games:", nrow(high_intensity), "\n")

# Analyze retention tiers
active_data$retention_tier <- cut(active_data$dauMauRatio,
                                  breaks = c(0, 0.1, 0.2, 0.3, 0.5, 1),
                                  labels = c("Poor", "Below Avg", "Good", 
                                            "Excellent", "Outstanding"))

retention_summary <- table(active_data$retention_tier[active_data$dau > 100])
barplot(retention_summary,
        main = "Games by Retention Tier (DAU > 100)",
        xlab = "Retention Tier",
        ylab = "Number of Games",
        col = rainbow(5))

# Monthly trend analysis
month_ago <- as.Date("2024-01-15") - 30
active_prev <- vgi_active_players_by_date(as.character(month_ago))

trend <- merge(active_data, active_prev,
              by = "steamAppId",
              suffixes = c("_now", "_prev"))

# Calculate monthly growth
trend$dau_growth <- ((trend$dau_now - trend$dau_prev) / 
                    (trend$dau_prev + 1)) * 100
trend$mau_growth <- ((trend$mau_now - trend$mau_prev) / 
                    (trend$mau_prev + 1)) * 100

# Find rapidly growing games
growing <- trend[trend$dau_growth > 50 & trend$dau_now > 1000, ]
cat("Games with >50% DAU growth:", nrow(growing), "\n")

# Identify games losing players
declining <- trend[trend$mau_growth < -20 & trend$mau_prev > 5000, ]
cat("Games losing >20% MAU:", nrow(declining), "\n")
print(head(declining[order(declining$mau_growth), 
           c("steamAppId", "mau_prev", "mau_now", "mau_growth")]))

## End(Not run)

Get Game IDs for Developers

Description

Retrieve the VGI game IDs attached to each developer from ⁠/companies/developers/game-ids⁠. Games on every platform are included; use vgi_developer_games() for one developer's Steam App IDs.

Usage

vgi_all_developer_games(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  vgi_ids = NULL,
  slugs = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with columns developer_id, name, game_ids (list-column of VGI game IDs) and game_count; see vgi_all_publisher_games().

Examples

## Not run: 
vgi_all_developer_games(vgi_ids = 28663)

## End(Not run)

Get Player Overlap Across the Catalogue

Description

Walk ⁠/player-overlap⁠ game by game, starting after cursor. The endpoint returns one game per request, so limit games cost limit requests and each row can be large. For one game use vgi_player_overlap().

Usage

vgi_all_games_player_overlap(
  limit = 1,
  cursor = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with one row per game: vgi_id, steam_app_id, top_overlaps (list-column of overlap tibbles, see vgi_player_overlap()), overlap_count, top_overlap_game (VGI ID) and top_overlap_pct, sorted by top_overlap_pct. The attribute next_cursor carries the cursor for the next game.

Examples

## Not run: 
vgi_all_games_player_overlap(limit = 5)

## End(Not run)

Get Playtime for Many Games (v4)

Description

Retrieve playtime statistics for many games from the v4 ⁠/player-insights/games/playtime⁠ endpoint, optionally restricted to players in given countries or regions. For one Steam game use vgi_insights_playtime().

Usage

vgi_all_games_playtime(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  steam_app_ids = NULL,
  vgi_ids = NULL,
  slugs = NULL,
  countries = NULL,
  regions = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with one row per game: vgi_id, platform, steam_app_id, avg_playtime, median_playtime (minutes), avg_playtime_rank, avg_playtime_prct, playtime_ranges (list-column of tibbles with range, percentage) and playtime_rank (rank by average playtime within the returned rows). The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_all_games_playtime(steam_app_ids = 4019220, countries = "US")

## End(Not run)

Get Player Regions for Many Games (v4)

Description

Retrieve the player-share-by-region breakdown for many games from the v4 ⁠/player-insights/games/top-regions⁠ endpoint, widened to one column per region. For one Steam game use vgi_top_regions().

Usage

vgi_all_games_regions(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  steam_app_ids = NULL,
  vgi_ids = NULL,
  slugs = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with one row per game: vgi_id, platform, steam_app_id, north_america, europe, asia, south_america, oceania, africa, middle_east (percentages) and dominant_region. The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_all_games_regions(steam_app_ids = 4019220)

## End(Not run)

Get Top Countries for Many Games (v4)

Description

Retrieve the player-share-by-country breakdown for many games from the v4 ⁠/player-insights/games/top-countries⁠ endpoint. Games can be selected by Steam App ID, VGI ID or slug; without identifiers the catalogue is paged from the cursor. For one Steam game use vgi_top_countries().

Usage

vgi_all_games_top_countries(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  steam_app_ids = NULL,
  vgi_ids = NULL,
  slugs = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with one row per game: vgi_id, platform, steam_app_id, top_countries (list-column of tibbles with country, country_name, percentage, rank), country_count, top_country, top_country_pct. The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
tc <- vgi_all_games_top_countries(steam_app_ids = c(4019220, 730))
tc$top_countries[[1]]

## End(Not run)

Get Top Wishlist Countries for Many Games (v4)

Description

Retrieve the wishlist-share-by-country breakdown for many games from the v4 ⁠/player-insights/games/top-wishlist-countries⁠ endpoint. For one Steam game use vgi_top_wishlist_countries().

Usage

vgi_all_games_wishlist_countries(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  steam_app_ids = NULL,
  vgi_ids = NULL,
  slugs = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with one row per game: vgi_id, platform, steam_app_id, top_wishlist_countries (list-column of tibbles with country, country_name, percentage, rank), wishlist_country_count, top_wishlist_country, top_wishlist_country_pct. The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_all_games_wishlist_countries(slugs = "dressmaker")

## End(Not run)

Get Game IDs for Publishers

Description

Retrieve the VGI game IDs attached to each publisher from ⁠/companies/publishers/game-ids⁠. Games on every platform are included; use vgi_publisher_games() for one publisher's Steam App IDs.

Usage

vgi_all_publisher_games(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  vgi_ids = NULL,
  slugs = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with columns publisher_id, name, game_ids (list-column of VGI game IDs) and game_count, sorted by game count. The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_all_publisher_games(vgi_ids = 28663)

## End(Not run)

Check VGI API Authentication

Description

Performs a lightweight authenticated request to verify that the configured credentials can access the API. Returns TRUE on success; otherwise FALSE with an informative message.

Usage

vgi_auth_check(auth_token = Sys.getenv("VGI_AUTH_TOKEN"))

Arguments

Value

Logical indicating whether authentication appears valid.

Build Complete Game Cache

Description

Fetches all games from the API and caches them locally with metadata. This is a one-time operation that should be run periodically to update the cache.

Usage

vgi_build_cache(
  force_refresh = FALSE,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN")
)

Arguments

Value

Invisible TRUE on success

Examples

## Not run: 
# Build initial cache
vgi_build_cache()

# Force refresh of cache
vgi_build_cache(force_refresh = TRUE)

## End(Not run)

Get Cache Statistics

Description

Display information about the current cache.

Usage

vgi_cache_stats()

Value

Invisible list with cache statistics

Clear VGI Cache

Description

Remove the cached game database.

Usage

vgi_clear_cache(confirm = TRUE)

Arguments

Value

Invisible TRUE

Get Concurrent Players Data by Date

Description

Retrieve concurrent player counts for all games on a specific date, providing a snapshot of active player engagement across the market.

Usage

vgi_concurrent_players_by_date(
  date,
  steam_app_ids = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

Concurrent player data is one of the most important engagement metrics:

• Real-time indicator of game health

• Direct measure of active player base

• Useful for identifying trending games

• Critical for multiplayer game analysis

• Key metric for seasonal event planning

Peak concurrent typically occurs during prime gaming hours, while average provides a more stable engagement metric.

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

peakConcurrent

Integer. Peak concurrent players on this date

avgConcurrent

Integer. Average concurrent players on this date

concurrentRank

Integer. Rank by peak concurrent players

Examples

## Not run: 
# Get concurrent player data
ccu_data <- vgi_concurrent_players_by_date("2024-01-15")

# Top 20 games by concurrent players
top_ccu <- head(ccu_data, 20)
cat("Top 20 games by peak concurrent players:\n")
print(top_ccu[, c("steamAppId", "peakConcurrent", "avgConcurrent")])

# Calculate peak-to-average ratio (indicates play pattern)
ccu_data$peak_avg_ratio <- ccu_data$peakConcurrent / 
                          (ccu_data$avgConcurrent + 1)

# Games with spiky play patterns (high peak/avg ratio)
spiky_games <- ccu_data[ccu_data$peak_avg_ratio > 3 & 
                        ccu_data$peakConcurrent > 1000, ]
cat("Games with concentrated play times:", nrow(spiky_games), "\n")

# Compare weekend vs weekday
is_weekend <- weekdays(as.Date("2024-01-15")) %in% c("Saturday", "Sunday")
if (!is_weekend) {
  # Get previous weekend data
  last_saturday <- as.Date("2024-01-15") - 
                  ((as.numeric(format(as.Date("2024-01-15"), "%w")) + 1) %% 7)
  weekend_ccu <- vgi_concurrent_players_by_date(as.character(last_saturday))
  
  comparison <- merge(ccu_data, weekend_ccu,
                     by = "steamAppId",
                     suffixes = c("_weekday", "_weekend"))
  
  # Calculate weekend boost
  comparison$weekend_boost <- (comparison$peakConcurrent_weekend - 
                              comparison$peakConcurrent_weekday) / 
                             comparison$peakConcurrent_weekday * 100
  
  # Games with biggest weekend boost
  weekend_games <- comparison[comparison$weekend_boost > 50 & 
                             comparison$peakConcurrent_weekday > 500, ]
  cat("Games with >50% weekend boost:", nrow(weekend_games), "\n")
}

# Analyze player concentration
total_players <- sum(ccu_data$peakConcurrent)
top_10_players <- sum(head(ccu_data$peakConcurrent, 10))
concentration <- (top_10_players / total_players) * 100

cat(sprintf("Top 10 games account for %.1f%% of all concurrent players\n", 
            concentration))

# Distribution analysis
hist(log10(ccu_data$peakConcurrent + 1),
     breaks = 40,
     main = "Distribution of Peak Concurrent Players (log scale)",
     xlab = "Log10(Peak CCU + 1)",
     col = "orange")

# Find multiplayer vs single-player patterns
# (Multiplayer games typically have higher avg/peak ratios)
ccu_data$avg_peak_ratio <- ccu_data$avgConcurrent / 
                          (ccu_data$peakConcurrent + 1)
likely_multiplayer <- ccu_data[ccu_data$avg_peak_ratio > 0.6 & 
                              ccu_data$peakConcurrent > 1000, ]
cat("Likely multiplayer games (high avg/peak):", nrow(likely_multiplayer), "\n")

## End(Not run)

Get a Developer's Steam Games

Description

Retrieve the Steam App IDs of the games a company develops. The VGI game IDs from ⁠/companies/developers/game-ids⁠ are resolved to Steam App IDs through ⁠/games/metadata⁠; games that are not on Steam are dropped. For the VGI IDs of games on every platform use vgi_all_developer_games().

Usage

vgi_developer_games(
  company_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

An integer vector of Steam App IDs, sorted (empty when none).

Examples

## Not run: 
vgi_developer_games(28663)

## End(Not run)

Get Developer Information

Description

Retrieve a developer's summary from ⁠/companies/developers⁠. Revenue and game counts are VGI's Steam figures; release counts are given per platform. For many developers or the full per-platform breakdown use vgi_developers_overview().

Usage

vgi_developer_info(
  company_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A one-row tibble with columns company_id, name, slug, classification, country, games_developed, games_in_development, revenue_total, revenue_avg_per_game, revenue_median_per_game, games_released_steam, games_released_playstation, games_released_xbox and vgi_url. Empty when the developer is unknown.

Examples

## Not run: 
vgi_developer_info(28663)

## End(Not run)

Get Developer Names and IDs

Description

Retrieve the developer directory from ⁠/companies/developers/list⁠, which pages with a cursor and includes slugs.

Usage

vgi_developer_list(
  search = NULL,
  limit = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  vgi_ids = NULL,
  slugs = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with columns id, name, slug and vgi_url, sorted by name. The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_developer_list(search = "free lives")

## End(Not run)

Get Developer Overview (v4, multi-platform)

Description

Retrieve developer summaries from the v4 ⁠/companies/developers⁠ endpoint, including per-platform revenue, release counts and genre breakdowns.

Usage

vgi_developers_overview(
  vgi_ids = NULL,
  slugs = NULL,
  cursor = NULL,
  limit = 100,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  all_pages = FALSE
)

Arguments

Value

A tibble with one row per publisher: vgi_company_id, name, slug, classification, country, vgi_url and the flattened ⁠platform_data.<platform>.<metric>⁠ columns (for example platform_data.steam.revenue_total, platform_data.steam.genre_breakdown.rpg). The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_developers_overview(slugs = "free-lives")

## End(Not run)

Smart Fetch Functions for VGI API

Description

These functions handle pagination and ID-based fetching intelligently Fetch All Games with Pagination

Usage

vgi_fetch_all_games(
  cache_results = TRUE,
  verbose = TRUE,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN")
)

Arguments

Details

Fetches all games from the API by handling pagination automatically. Results are cached to avoid repeated API calls.

Value

Data frame with all games

Fetch Games by ID List

Description

Fetch game data for a list of Steam App IDs: metadata from ⁠/games/metadata⁠, or one day's active players from ⁠/historical-data⁠.

Usage

vgi_fetch_by_ids(
  steam_app_ids,
  data_type = c("metadata", "active_players"),
  date = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN")
)

Arguments

Value

A tibble with the requested game data.

Examples

## Not run: 
games <- vgi_fetch_by_ids(c(730, 578080, 1172470), "metadata")
active <- vgi_fetch_by_ids(c(730, 578080), "active_players", date = "2025-07-26")

## End(Not run)

Filter Games by Genre

Description

Filter cached games by genre without hitting the API. VGI assigns each game one genre (for example "Shooter"); Steam's own genres are in steam_genres and steam_subgenres. source picks which to match.

Usage

vgi_filter_genre(genre, cache_df = NULL, source = c("vgi", "steam"))

Arguments

Value

A tibble of the matching games.

Examples

## Not run: 
shooters <- vgi_filter_genre("Shooter")
steam_shooters <- vgi_filter_genre("Shooter", source = "steam")

## End(Not run)

Get Followers Data by Date

Description

Retrieve follower counts for all games on a specific date, useful for tracking market-wide community engagement trends.

Usage

vgi_followers_by_date(
  date,
  steam_app_ids = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

Steam followers represent users who want to stay updated about a game. This metric is valuable for:

• Measuring long-term community engagement

• Tracking marketing campaign effectiveness

• Identifying games with growing communities

• Benchmarking community size across genres

• Early warning for declining interest

Unlike wishlists, followers persist after game purchase, making this a good metric for both released and unreleased games.

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

followerCount

Integer. Number of followers

followerRank

Integer. Rank by follower count

Examples

## Not run: 
# Get follower data for a specific date
followers <- vgi_followers_by_date("2024-01-15")

# Top 20 most followed games
top_followed <- head(followers, 20)
print(top_followed)

# Compare with wishlist data to find engagement patterns
wishlists <- vgi_wishlists_by_date("2024-01-15")
engagement <- merge(followers, wishlists, by = "steamAppId")
engagement$follow_to_wishlist_ratio <- 
  engagement$followerCount / (engagement$wishlistCount + 1)

# Games with high follower/wishlist ratio (strong community)
high_engagement <- engagement[engagement$follow_to_wishlist_ratio > 2 & 
                              engagement$followerCount > 10000, ]
cat("High community engagement games:", nrow(high_engagement), "\n")

# Monthly follower growth analysis
month_ago <- as.Date("2024-01-15") - 30
followers_prev <- vgi_followers_by_date(as.character(month_ago))

growth <- merge(followers, followers_prev,
               by = "steamAppId",
               suffixes = c("_now", "_prev"))
growth$monthly_change <- growth$followerCount_now - growth$followerCount_prev
growth$monthly_pct <- (growth$monthly_change / growth$followerCount_prev) * 100

# Fastest growing communities (min 5000 followers)
qualified <- growth[growth$followerCount_prev >= 5000, ]
fastest <- head(qualified[order(-qualified$monthly_pct), ], 20)

cat("Fastest growing communities (>5000 followers):\n")
print(fastest[, c("steamAppId", "followerCount_now", 
                 "monthly_change", "monthly_pct")])

# Find games losing followers
declining <- growth[growth$monthly_change < -500, ]
cat("Games losing 500+ followers this month:", nrow(declining), "\n")

# Analyze follower distribution by tier
follower_tiers <- cut(followers$followerCount,
                     breaks = c(0, 1000, 10000, 50000, 100000, Inf),
                     labels = c("<1K", "1K-10K", "10K-50K", "50K-100K", ">100K"))
tier_summary <- table(follower_tiers)

barplot(tier_summary,
        main = "Distribution of Games by Follower Count",
        xlab = "Follower Tier",
        ylab = "Number of Games",
        col = "skyblue")

## End(Not run)

Get the Full Game List

Description

Retrieve the catalogue of games known to VGI, on every platform, from ⁠/games/game-list⁠. The response is large (several MB) and unpaginated; consider caching the result.

Usage

vgi_game_list(auth_token = Sys.getenv("VGI_AUTH_TOKEN"), headers = list())

Arguments

Value

A tibble with columns vgi_id, steam_app_id (NA for games that are not on Steam) and name, sorted by VGI ID.

Examples

## Not run: 
games <- vgi_game_list()
nrow(games)

## End(Not run)

Get Game Metadata for a Steam Game

Description

Retrieves the metadata of one Steam game from ⁠/games/metadata⁠. The row has the multi-platform shape of vgi_games_metadata(): VGI's own genre and subgenre, Steam's steam_genres and steam_subgenres, per-platform prices, release dates and store URLs, plus list-columns for tags, modes, themes, developers and publishers.

Usage

vgi_game_metadata(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A one-row tibble with the columns of vgi_games_metadata(). An empty tibble is returned when the API has no such game.

Examples

## Not run: 
vgi_game_metadata(4019220)$name

## End(Not run)

Get Metadata for Several Steam Games

Description

Retrieves metadata for multiple Steam games from ⁠/games/metadata⁠, up to 500 IDs per request. When the API rejects a request because one ID is unknown, that chunk is fetched one game at a time.

Usage

vgi_game_metadata_batch(
  steam_app_ids,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with one row per game found, in the shape of vgi_games_metadata(). IDs the API does not know are reported in a warning.

Examples

## Not run: 
vgi_game_metadata_batch(c(892970, 1245620, 105600))

## End(Not run)

Get Comprehensive Game Summary

Description

Retrieve all available metrics for specified games over a date range. This function aggregates data from multiple VGI endpoints to provide a complete overview of game performance.

Usage

vgi_game_summary(
  steam_app_ids,
  start_date,
  end_date = NULL,
  metrics = c("concurrent", "active", "revenue", "units"),
  game_names = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  batch_size = NULL,
  batch_delay = NULL
)

Arguments

Details

This function makes multiple API calls to gather comprehensive data. For efficiency, it uses the steamAppIds parameter where supported.

Note: Some endpoints may have data availability limitations:

• Active players: DAU from 2024-03-18, MAU from 2024-03-23

• Some metrics may not be available for all games

Value

A list containing:

summary_table

Aggregated metrics for each game

time_series

List of time series data frames by metric

metadata

Game metadata if requested

api_calls

Number of API calls made

errors

Any errors encountered during data collection

Examples

## Not run: 
# Analyze a single game for one week
bf5_summary <- vgi_game_summary(
  steam_app_ids = 1238810,  # Battlefield V
  start_date = "2024-07-01",
  end_date = "2024-07-07"
)

# Analyze multiple games
battlefield_summary <- vgi_game_summary(
  steam_app_ids = c(1517290, 1238810),  # BF2042 and BFV
  start_date = "2024-07-01", 
  end_date = "2024-07-07",
  metrics = c("concurrent", "active", "revenue", "units")
)

# View summary table
print(battlefield_summary$summary_table)

# Plot time series
ggplot(battlefield_summary$time_series$concurrent,
       aes(x = date, y = peakConcurrent, color = factor(steamAppId))) +
  geom_line() +
  labs(title = "Peak CCU Over Time")

## End(Not run)

Get Year-over-Year Game Summary Comparison

Description

Compare game metrics across multiple years for the same time period. Supports flexible date specification using months or explicit dates.

Usage

vgi_game_summary_yoy(
  steam_app_ids,
  years,
  start_month = NULL,
  end_month = NULL,
  start_date = NULL,
  end_date = NULL,
  metrics = c("concurrent", "revenue", "units"),
  include_growth = TRUE,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  batch_size = NULL,
  batch_delay = NULL
)

Arguments

Details

The function supports two ways to specify the comparison period:

1. Month-based: Specify start_month and optionally end_month. The function will use these months for each year in the years parameter.

2. Date-based: Specify start_date and end_date with explicit month/day (e.g., "03-15" for March 15). These will be applied to each year.

Year-over-year growth is calculated as: ((current - previous) / previous) * 100

Value

A vgi_yoy_comparison object (classed list) containing:

comparison_table

Data frame of per-game metrics by year, with optional year-over-year growth columns.

yearly_summaries

Named list of full vgi_game_summary() outputs, one entry per year in the comparison.

time_series_comparison

Named list of combined time-series data frames (e.g., concurrent, revenue, units) with normalized dates for cross-year plotting.

period

Human-readable description of the comparison window.

years

Sorted numeric vector of years that were compared.

api_calls

Total number of API calls made across all years.

Examples

## Not run: 
# Compare Q1 performance across years
q1_comparison <- vgi_game_summary_yoy(
  steam_app_ids = c(892970, 1145360),
  years = c(2023, 2024, 2025),
  start_month = "Jan",
  end_month = "Mar"
)

# Compare specific date ranges
holiday_comparison <- vgi_game_summary_yoy(
  steam_app_ids = 892970,
  years = c(2022, 2023, 2024),
  start_date = "11-15",  # Nov 15
  end_date = "01-15"     # Jan 15 (crosses year boundary)
)

# Compare full years
yearly_comparison <- vgi_game_summary_yoy(
  steam_app_ids = c(1517290, 1238810),
  years = c(2023, 2024),
  start_month = "January",
  end_month = "December"
)

## End(Not run)

Get Game Metadata for Many Games (v4, multi-platform)

Description

Retrieve metadata from the v4 ⁠/games/metadata⁠ endpoint. Games can be selected by Steam App ID, VGI ID or slug, and the endpoint pages with a cursor. Without any identifiers it lists the catalogue from the cursor.

Usage

vgi_games_metadata(
  steam_app_ids = NULL,
  vgi_ids = NULL,
  slugs = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with one row per game: vgi_id, slug, name, steam_app_id (parsed from the Steam store URL), per-platform columns price_steam, price_xbox, price_playstation, release_date_steam, release_date_xbox, release_date_playstation, store_url_steam, store_url_xbox, store_url_playstation, plus steam_full_release_date, genre, subgenre, steam_genres, steam_subgenres, languages, publisher_classification, publishing_type, vgi_url, publisher_id, publisher_name, developer_id, developer_name, and list-columns platforms, game_engines, steam_tags, themes, art_styles, character, game_modes, developers, publishers. The attribute next_cursor carries the cursor for the next page (NULL when exhausted).

Examples

## Not run: 
vgi_games_metadata(steam_app_ids = 4019220)
vgi_games_metadata(slugs = "dressmaker")$vgi_id

# Page through the catalogue 500 games at a time
page1 <- vgi_games_metadata(limit = 500)
page2 <- vgi_games_metadata(limit = 500, cursor = attr(page1, "next_cursor"))

## End(Not run)

Get Games by Steam App IDs

Description

Retrieve game information for specific Steam App IDs from the cache, fetching any missing games from ⁠/games/metadata⁠.

Usage

vgi_get_games_by_id(steam_app_ids, cache_df = NULL, fetch_missing = TRUE)

Arguments

Value

A tibble with one row per game found.

Examples

## Not run: 
games <- vgi_get_games_by_id(c(730, 578080, 1172470))

## End(Not run)

Get Full Historical Data for a Game

Description

Retrieve the complete daily history for a single Steam game and split it into tidy per-metric time series.

Usage

vgi_historical_data(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

For a single-date snapshot across many games (including the v4 multi-platform, country and region breakdowns) use vgi_historical_data_by_date().

Value

A list with element steam_app_id plus one tibble (or NULL when the API has no data for that metric) for each of:

revenue

date, revenue (cumulative total), daily_revenue; v4 ⁠premiumRevenue*⁠ fields

units_sold

date, units_sold (cumulative total), daily_units; v4 ⁠unitsOwned*⁠ fields

concurrent_players

date, ccu_avg, ccu_median, ccu_max, ccu_min

active_players

date, dau, mau

reviews

date, positive, negative, positive_change, negative_change

wishlists

date, wishlists, wishlists_change

followers

date, followers, followers_change

price_history

date, price_initial, price_final

The daily element holds the raw flat daily table with every metric column returned by the API (snake_case).

Examples

## Not run: 
hist <- vgi_historical_data(4019220)
hist$concurrent_players
hist$revenue

## End(Not run)

Get a Historical Data Snapshot for a Date (v4)

Description

Retrieve one day of metrics for many games at once from the v4 ⁠/historical-data⁠ endpoint. The v4 endpoint is multi-platform and can break the numbers down by country or region.

Usage

vgi_historical_data_by_date(
  date,
  steam_app_ids = NULL,
  vgi_ids = NULL,
  slugs = NULL,
  countries = NULL,
  regions = NULL,
  limit = NULL,
  cursor = NULL,
  all_pages = FALSE,
  platforms = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with one row per game (and platform / country / region when requested). Columns are the snake_case API fields, e.g. vgi_id, platform, external_id, steam_app_id (NA for non-steam rows), date, country, revenue_total, revenue_change, units_sold_total, dau, mau, wishlists_total, ccu_max, price_final. The attribute next_cursor carries the cursor for the next page (NULL when exhausted).

Examples

## Not run: 
snap <- vgi_historical_data_by_date("2026-09-28", steam_app_ids = 4019220)
snap[, c("steam_app_id", "ccu_max", "revenue_total")]

# Country breakdown
vgi_historical_data_by_date("2026-09-28", steam_app_ids = 4019220,
                            countries = c("US", "DE"))

## End(Not run)

Get Concurrent Users (CCU) Data

Description

Retrieve the daily concurrent player history for a single Steam game.

Usage

vgi_insights_ccu(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A list containing:

steam_app_id

Integer. The Steam App ID

player_history

Tibble with columns date, avg, median, max, min (concurrent players), sorted by date

Examples

## Not run: 
ccu <- vgi_insights_ccu(steam_app_id = 4019220)
plot(ccu$player_history$date, ccu$player_history$max, type = "l")

## End(Not run)

Get Daily and Monthly Active Users (DAU/MAU)

Description

Retrieve the active player history for a single Steam game.

Usage

vgi_insights_dau_mau(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

DAU is available from 2024-03-18 and MAU from 2024-03-23.

Value

A list containing:

steam_app_id

Integer. The Steam App ID

player_history

Tibble with columns date, dau, mau

Examples

## Not run: 
active <- vgi_insights_dau_mau(steam_app_id = 4019220)
tail(active$player_history)

## End(Not run)

Get Follower History for a Game

Description

Retrieve the Steam follower history for a single game.

Usage

vgi_insights_followers(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A list containing:

steam_app_id

Integer. The Steam App ID

followers_change

Tibble with columns date, followers_total, followers_change

Examples

## Not run: 
fol <- vgi_insights_followers(steam_app_id = 4019220)
tail(fol$followers_change)

## End(Not run)

Get Player Region Distribution for a Game

Description

Retrieve the share of players by world region for a single Steam game.

Usage

vgi_insights_player_regions(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A list containing steam_app_id and regions, a tibble with columns region_name, rank and percentage, sorted by rank.

See Also

vgi_top_regions() returns just the regions tibble.

Examples

## Not run: 
vgi_insights_player_regions(steam_app_id = 4019220)$regions

## End(Not run)

Get Playtime Insights for a Game

Description

Retrieve playtime statistics for a single Steam game. For many games at once, or for country / region filtered playtime, use vgi_all_games_playtime() (v4).

Usage

vgi_insights_playtime(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A list containing steam_app_id, avg_playtime and median_playtime (minutes), avg_playtime_rank, avg_playtime_prct, and playtime_ranges, a tibble with columns range and percentage.

Examples

## Not run: 
pt <- vgi_insights_playtime(steam_app_id = 4019220)
pt$median_playtime
pt$playtime_ranges

## End(Not run)

Get Price History Data for a Game

Description

Retrieve the Steam price-change periods for a game: the Steam rows of vgi_price_history(), which also covers PlayStation and Xbox prices and VGI-id or slug lookup.

Usage

vgi_insights_price_history(
  steam_app_id,
  currency = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A list containing:

steam_app_id

Integer. The Steam App ID

currency

Character. The requested currency, or "ALL"

price_changes

Tibble with columns currency, price_initial, price_final, first_date, last_date (NA for the current period), newest period first

Examples

## Not run: 
usd <- vgi_insights_price_history(4019220, currency = "USD")
usd$price_changes

all_prices <- vgi_insights_price_history(4019220)
table(all_prices$price_changes$currency)

## End(Not run)

Get Revenue History for a Game

Description

Retrieve the daily revenue history for a single Steam game. In v4 the figures come from premiumRevenueChange / premiumRevenueTotal (the successors of the deprecated revenueChange / revenueTotal).

Usage

vgi_insights_revenue(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with columns:

steam_app_id

Integer. The Steam App ID

date

Date

revenue_change

Numeric. Revenue earned on that day (USD)

revenue_total

Numeric. Cumulative revenue to date (USD)

Examples

## Not run: 
rev <- vgi_insights_revenue(steam_app_id = 4019220)
plot(rev$date, rev$revenue_change, type = "l")

## End(Not run)

Get Review History for a Game

Description

Retrieve the daily Steam review history for a single game.

Usage

vgi_insights_reviews(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with columns steam_app_id, date, positive, negative (cumulative totals), total, positive_ratio, positive_change and negative_change (reviews added that day).

Examples

## Not run: 
reviews <- vgi_insights_reviews(steam_app_id = 4019220)
tail(reviews[, c("date", "positive", "negative", "positive_ratio")])

## End(Not run)

Get Units Sold History for a Game

Description

Retrieve the daily units history for a single Steam game. In v4 the figures come from unitsOwnedChange / unitsOwnedTotal (the successors of the deprecated unitsSoldChange / unitsSoldTotal; they include copies obtained for free).

Usage

vgi_insights_units(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with columns:

steam_app_id

Integer. The Steam App ID

date

Date

units_sold_change

Integer. Units sold on that day

units_sold_total

Integer. Cumulative units sold to date

Examples

## Not run: 
units <- vgi_insights_units(steam_app_id = 4019220)
max(units$units_sold_total)

## End(Not run)

Get Wishlist History for a Game

Description

Retrieve the outstanding-wishlist history for a single Steam game.

Usage

vgi_insights_wishlists(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A list containing:

steam_app_id

Integer. The Steam App ID

wishlist_changes

Tibble with columns date, wishlists_total, wishlists_change

Examples

## Not run: 
wl <- vgi_insights_wishlists(steam_app_id = 4019220)
tail(wl$wishlist_changes)

## End(Not run)

Load Game Cache

Description

Loads the cached game database.

Usage

vgi_load_cache(auto_build = TRUE)

Arguments

Value

Data frame with all cached games and metadata

Get peak concurrent players (CCU) for multiple Steam app IDs

Description

Get peak concurrent players (CCU) for multiple Steam app IDs

Usage

vgi_peak_ccu_by_ids(steam_app_ids)

Arguments

Value

A tibble with columns: name, steam_app_id, peak_ccu, peak_date

Get peak concurrent players (CCU) for multiple games by names

Description

Resolves each game name to a Steam app ID using vgi_search_games(title, limit = 5) with a simple exact/startsWith prioritization, then fetches peak CCU via vgi_insights_ccu() per resolved ID. No all-games endpoints are used.

Usage

vgi_peak_ccu_by_names(game_names)

Arguments

Value

A tibble with columns: input_name, name, steam_app_id, peak_ccu, peak_date

Get Player Overlap for a Game

Description

Retrieve the games whose audiences overlap most with a given game from ⁠/player-overlap⁠. Identify the game by Steam App ID, VGI ID or slug.

Usage

vgi_player_overlap(
  steam_app_id = NULL,
  limit = 10,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  vgi_id = NULL,
  slug = NULL
)

Arguments

Value

A list containing:

steam_app_id

Integer. The requested game (NA for non-Steam games)

vgi_id

Integer. VGI ID of the requested game

player_overlaps

Tibble with one row per overlapping game: steam_app_id, vgi_id, median_playtime, units_sold_overlap, units_sold_overlap_percentage, units_sold_overlap_index, mau_overlap, mau_overlap_percentage, mau_overlap_index, wishlist_overlap, wishlist_overlap_percentage, wishlist_overlap_index

Examples

## Not run: 
ov <- vgi_player_overlap(4019220, limit = 20)
head(ov$player_overlaps)

vgi_player_overlap(slug = "dressmaker")

## End(Not run)

Get Price History for a Game (v4, multi-platform)

Description

Retrieve price-change periods for a game from the v4 ⁠/price-history⁠ endpoint. Exactly one of steam_app_id, vgi_id or slug identifies the game. For Steam prices only see vgi_insights_price_history().

Usage

vgi_price_history(
  steam_app_id = NULL,
  vgi_id = NULL,
  slug = NULL,
  currency = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with one row per price period and columns platform, external_id, currency, price_initial, price_final, first_date, last_date (NA for the current period).

Examples

## Not run: 
vgi_price_history(steam_app_id = 4019220, currency = "USD")
vgi_price_history(slug = "dressmaker")

## End(Not run)

Get a Publisher's Steam Games

Description

Retrieve the Steam App IDs of the games a company publishes. The VGI game IDs from ⁠/companies/publishers/game-ids⁠ are resolved to Steam App IDs through ⁠/games/metadata⁠; games that are not on Steam are dropped. For the VGI IDs of games on every platform use vgi_all_publisher_games().

Usage

vgi_publisher_games(
  company_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

An integer vector of Steam App IDs, sorted (empty when none).

Examples

## Not run: 
vgi_publisher_games(28663)

## End(Not run)

Get Publisher Information

Description

Retrieve a publisher's summary from ⁠/companies/publishers⁠. Revenue and game counts are VGI's Steam figures; release counts are given per platform. For many publishers or the full per-platform breakdown use vgi_publishers_overview().

Usage

vgi_publisher_info(
  company_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A one-row tibble with columns company_id, name, slug, classification, country, games_published, games_in_development, revenue_total, revenue_avg_per_game, revenue_median_per_game, games_released_steam, games_released_playstation, games_released_xbox and vgi_url. Empty when the publisher is unknown.

Examples

## Not run: 
vgi_publisher_info(28663)

## End(Not run)

Get Publisher Names and IDs

Description

Retrieve the publisher directory from ⁠/companies/publishers/list⁠, which pages with a cursor and includes slugs.

Usage

vgi_publisher_list(
  search = NULL,
  limit = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  vgi_ids = NULL,
  slugs = NULL,
  cursor = NULL,
  all_pages = FALSE
)

Arguments

Value

A tibble with columns id, name, slug and vgi_url, sorted by name. The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_publisher_list(search = "valve")
vgi_publisher_list(slugs = "free-lives")

## End(Not run)

Get Publisher Overview (v4, multi-platform)

Description

Retrieve publisher summaries from the v4 ⁠/companies/publishers⁠ endpoint, including per-platform revenue, release counts and genre breakdowns.

Usage

vgi_publishers_overview(
  vgi_ids = NULL,
  slugs = NULL,
  cursor = NULL,
  limit = 100,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  all_pages = FALSE
)

Arguments

Value

A tibble with one row per publisher: vgi_company_id, name, slug, classification, country, vgi_url and the flattened ⁠platform_data.<platform>.<metric>⁠ columns (for example platform_data.steam.revenue_total, platform_data.steam.genre_breakdown.rpg). The attribute next_cursor carries the cursor for the next page.

Examples

## Not run: 
vgi_publishers_overview(vgi_ids = 28663)
vgi_publishers_overview(limit = 500)

## End(Not run)

Get Revenue Data by Date

Description

Retrieve revenue data for all games on a specific date, providing a comprehensive view of market financial performance.

Usage

vgi_revenue_by_date(
  date,
  steam_app_ids = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

Revenue data is the most important commercial metric for:

• Market size estimation

• Financial performance benchmarking

• ROI analysis

• Publisher/developer valuations

• Investment decisions

All revenue figures are in USD and represent gross revenue before platform fees and taxes.

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

revenue

Numeric. Cumulative revenue in USD as of this date

dailyRevenue

Numeric. Revenue generated on this specific day

revenueRank

Integer. Rank by total revenue

Examples

## Not run: 
# Get revenue data for a specific date
revenue_data <- vgi_revenue_by_date("2024-01-15")

# Top 20 highest-grossing games
top_revenue <- head(revenue_data, 20)
cat("Top 20 games by revenue:\n")
print(top_revenue[, c("steamAppId", "revenue", "dailyRevenue")])

# Format revenue for display
top_revenue$revenue_millions <- round(top_revenue$revenue / 1000000, 2)
cat("Top game revenue: $", top_revenue$revenue_millions[1], "M\n", sep = "")

# Calculate market concentration
total_revenue <- sum(revenue_data$revenue)
top_10_revenue <- sum(head(revenue_data$revenue, 10))
concentration <- (top_10_revenue / total_revenue) * 100
cat(sprintf("Top 10 games represent %.1f%% of total revenue\n", concentration))

# Daily revenue leaders
prev_date <- as.Date("2024-01-15") - 1
revenue_prev <- vgi_revenue_by_date(as.character(prev_date))

daily_rev <- merge(revenue_data, revenue_prev,
                  by = "steamAppId",
                  suffixes = c("_today", "_yesterday"))
daily_rev$revenue_today <- daily_rev$revenue_today - daily_rev$revenue_yesterday

# Games with highest daily revenue
top_daily_rev <- head(daily_rev[order(-daily_rev$revenue_today), ], 20)
cat("Top daily revenue generators:\n")
top_daily_rev$daily_rev_k <- round(top_daily_rev$revenue_today / 1000, 1)
print(top_daily_rev[, c("steamAppId", "daily_rev_k")])

# Revenue distribution analysis
revenue_tiers <- cut(revenue_data$revenue,
                    breaks = c(0, 10000, 100000, 1000000, 10000000, Inf),
                    labels = c("<$10K", "$10K-100K", "$100K-1M", 
                              "$1M-10M", ">$10M"))
tier_summary <- table(revenue_tiers)

barplot(tier_summary,
        main = "Games by Revenue Tier",
        xlab = "Revenue Tier",
        ylab = "Number of Games",
        col = "gold")

# Year-over-year growth analysis
last_year <- as.Date("2024-01-15") - 365
revenue_ly <- vgi_revenue_by_date(as.character(last_year))

yoy <- merge(revenue_data, revenue_ly,
            by = "steamAppId",
            suffixes = c("_now", "_lastyear"))
yoy$yoy_growth <- ((yoy$revenue_now - yoy$revenue_lastyear) / 
                  yoy$revenue_lastyear) * 100

# Fastest growing games by revenue
min_revenue <- 100000  # Only games with substantial revenue
qualified <- yoy[yoy$revenue_lastyear >= min_revenue, ]
fastest_growing <- head(qualified[order(-qualified$yoy_growth), ], 20)

cat("Fastest growing games (YoY revenue):\n")
print(fastest_growing[, c("steamAppId", "revenue_now", "yoy_growth")])

## End(Not run)

Get Reviews Data by Date

Description

Retrieve review data for all games on a specific date, useful for market-wide analysis and trend identification.

Usage

vgi_reviews_by_date(
  date,
  steam_app_ids = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

This endpoint enables:

• Daily market sentiment analysis

• Identifying games with review bombs or surges

• Tracking industry-wide review trends

• Comparing review activity across multiple games

• Building review trend dashboards

The data represents the cumulative review counts as of the specified date.

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

positiveReviews

Integer. Number of positive reviews

negativeReviews

Integer. Number of negative reviews

totalReviews

Integer. Total number of reviews

positiveRatio

Numeric. Ratio of positive reviews (0-1)

Examples

## Not run: 
# Get reviews for a specific date
reviews_data <- vgi_reviews_by_date("2024-01-15")

# Find games with most reviews on this date
top_reviewed <- head(reviews_data[order(-reviews_data$totalReviews), ], 20)
print(top_reviewed)

# Find games with best review ratios (min 100 reviews)
qualified <- reviews_data[reviews_data$totalReviews >= 100, ]
best_rated <- head(qualified[order(-qualified$positiveRatio), ], 20)
cat("Best rated games with 100+ reviews:\n")
print(best_rated[, c("steamAppId", "positiveRatio", "totalReviews")])

# Analyze review distribution
hist(reviews_data$positiveRatio[reviews_data$totalReviews >= 10],
     breaks = 20,
     main = "Distribution of Review Scores",
     xlab = "Positive Review Ratio",
     col = "lightblue")
abline(v = 0.7, col = "green", lwd = 2, lty = 2)
abline(v = 0.5, col = "orange", lwd = 2, lty = 2)

# Compare with previous date
prev_date <- as.Date("2024-01-15") - 1
prev_reviews <- vgi_reviews_by_date(as.character(prev_date))

# Merge to find daily changes
comparison <- merge(reviews_data, prev_reviews, 
                   by = "steamAppId", 
                   suffixes = c("_today", "_yesterday"))

# Calculate daily review additions
comparison$new_reviews <- comparison$totalReviews_today - comparison$totalReviews_yesterday
comparison$ratio_change <- comparison$positiveRatio_today - comparison$positiveRatio_yesterday

# Find games with biggest review changes
biggest_changes <- head(comparison[order(-abs(comparison$new_reviews)), ], 10)
cat("Games with most review activity:\n")
print(biggest_changes[, c("steamAppId", "new_reviews", "ratio_change")])

## End(Not run)

Search Games in Video Game Insights

Description

Search for games by title using the Video Game Insights database.

Usage

vgi_search_games(
  query,
  limit = 10,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list(),
  allow_api_fallback = getOption("vgi.search_allow_api_fallback", TRUE)
)

Arguments

Value

A tibble containing search results with game information including steamAppId and name.

Examples

## Not run: 
# Ensure the VGI_AUTH_TOKEN environment variable is set
# Sys.setenv(VGI_AUTH_TOKEN = "your_auth_token_here")

# Search for games with "valve" in the title
valve_games <- vgi_search_games("valve")
print(valve_games)

# Search with more results
rpg_games <- vgi_search_games("rpg", limit = 50)

## End(Not run)

Smart Game Search using Publisher/Developer Relationships

Description

This function performs intelligent game searches by finding one game that matches your query, then retrieving ALL games from the same publisher or developer. This is the RIGHT way to search for games - not by searching through a massive cached list.

Usage

vgi_smart_game_search(
  query,
  search_type = c("publisher", "developer"),
  limit = 50,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

This function implements the CORRECT way to search for games:

1. First, it finds ONE game that matches your query (from cache or API)

2. Then it gets the publisher or developer ID from that game's metadata

3. Finally, it retrieves ALL games from that publisher/developer

This is much smarter than searching through thousands of cached games and actually uses the API's relationship structure properly.

Example: Search for "Battlefield" -> finds one Battlefield game -> gets EA's publisher ID -> returns ALL EA games including all Battlefields.

Value

A tibble containing games from the same publisher/developer with columns:

steamAppId

Integer. The Steam App ID

name

Character. The game name

publisher

Character. Publisher name (if search_type="publisher")

developer

Character. Developer name (if search_type="developer")

releaseDate

Date. Game release date

Examples

## Not run: 
# Find all games from Battlefield's publisher (EA)
ea_games <- vgi_smart_game_search("battlefield", search_type = "publisher")
print(ea_games)

# Find all games from the developer of Gothic
gothic_dev_games <- vgi_smart_game_search("gothic", search_type = "developer")
print(gothic_dev_games)

## End(Not run)

Get Steam Market Data

Description

Retrieve monthly Steam-wide market totals (units, revenue, releases, users online, accounts) from ⁠/market-data⁠.

Usage

vgi_steam_market_data(
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with one row per month: period (YYYY-MM-01), units_total, revenue_total, releases_total, users_online, users_ingame, accounts_total and platform.

Examples

## Not run: 
market <- vgi_steam_market_data()
tail(market)

## End(Not run)

Get Top Countries for a Game

Description

Retrieve the countries with the largest share of a Steam game's players. For many games at once use vgi_all_games_top_countries().

Usage

vgi_top_countries(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with columns country (ISO code), country_name, percentage and rank, sorted by rank.

Examples

## Not run: 
vgi_top_countries(steam_app_id = 4019220)

## End(Not run)

Get Top Regions for a Game

Description

Convenience wrapper around vgi_insights_player_regions() that returns only the regions tibble.

Usage

vgi_top_regions(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with columns region_name, rank and percentage.

Examples

## Not run: 
vgi_top_regions(steam_app_id = 4019220)

## End(Not run)

Get Top Wishlist Countries for a Game

Description

Retrieve the countries contributing the largest share of a Steam game's wishlists, from v4 ⁠/player-insights/games/top-wishlist-countries⁠. For many games at once use vgi_all_games_wishlist_countries().

Usage

vgi_top_wishlist_countries(
  steam_app_id,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Value

A tibble with columns country (ISO code), country_name, percentage and rank, sorted by rank.

Examples

## Not run: 
vgi_top_wishlist_countries(steam_app_id = 4019220)

## End(Not run)

Get Units Sold Data by Date

Description

Retrieve units sold data for all games on a specific date, providing a market-wide view of sales performance.

Usage

vgi_units_sold_by_date(
  date,
  steam_app_ids = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

Units sold data is crucial for:

• Market share analysis

• Sales velocity tracking

• Launch performance benchmarking

• Seasonal sales pattern identification

• Competitive analysis

The data represents lifetime units sold through the specified date, with daily units calculated from sequential dates.

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

unitsSold

Integer. Cumulative units sold as of this date

dailyUnits

Integer. Units sold on this specific day

salesRank

Integer. Rank by total units sold

Examples

## Not run: 
# Get units sold data for a specific date
units_data <- vgi_units_sold_by_date("2024-01-15")

# Top 20 best-selling games
top_sellers <- head(units_data, 20)
cat("Top 20 best-selling games:\n")
print(top_sellers[, c("steamAppId", "unitsSold", "dailyUnits")])

# Calculate previous day's data for daily sales
prev_date <- as.Date("2024-01-15") - 1
units_prev <- vgi_units_sold_by_date(as.character(prev_date))

# Merge to calculate exact daily sales
daily_sales <- merge(units_data, units_prev,
                    by = "steamAppId",
                    suffixes = c("_today", "_yesterday"))
daily_sales$units_sold_today <- daily_sales$unitsSold_today - 
                                daily_sales$unitsSold_yesterday

# Find games with highest daily sales
top_daily <- head(daily_sales[order(-daily_sales$units_sold_today), ], 20)
cat("Top 20 games by daily sales:\n")
print(top_daily[, c("steamAppId", "units_sold_today")])

# Analyze sales distribution
hist(log10(units_data$unitsSold + 1),
     breaks = 40,
     main = "Distribution of Total Units Sold (log scale)",
     xlab = "Log10(Units Sold + 1)",
     col = "darkgreen")

# Sales velocity analysis
units_data$sales_per_day <- units_data$unitsSold / 
  as.numeric(as.Date("2024-01-15") - as.Date("2020-01-01"))

# Games with sustained high sales velocity
high_velocity <- units_data[units_data$sales_per_day > 100 & 
                           units_data$unitsSold > 100000, ]
cat("Games averaging >100 sales/day:", nrow(high_velocity), "\n")

# Compare with revenue data for average price calculation
revenue_data <- vgi_revenue_by_date("2024-01-15")
pricing <- merge(units_data, revenue_data, by = "steamAppId")
pricing$avg_price <- pricing$revenue / (pricing$unitsSold + 1)

# Find premium-priced successful games
premium_games <- pricing[pricing$avg_price > 40 & 
                        pricing$unitsSold > 50000, ]
cat("Premium games (>$40) with >50k sales:", nrow(premium_games), "\n")

## End(Not run)

Get Wishlists Data by Date

Description

Retrieve wishlist counts for all games on a specific date, useful for tracking market-wide interest and anticipation trends.

Usage

vgi_wishlists_by_date(
  date,
  steam_app_ids = NULL,
  auth_token = Sys.getenv("VGI_AUTH_TOKEN"),
  headers = list()
)

Arguments

Details

This endpoint enables:

• Market-wide wishlist trend analysis

• Identifying rising games before launch

• Tracking pre-release momentum

• Competitive wishlist benchmarking

• Seasonal wishlist pattern analysis

Wishlist data is particularly valuable for unreleased games as it's often the primary engagement metric available.

Value

A data frame with columns:

steamAppId

Integer. The Steam App ID

date

Character. The date of the data

wishlistCount

Integer. Number of wishlists

wishlistRank

Integer. Rank by wishlist count

Examples

## Not run: 
# Get wishlist data for a specific date
wishlists <- vgi_wishlists_by_date("2024-01-15")

# Top 20 most wishlisted games
top_wishlisted <- head(wishlists, 20)
print(top_wishlisted)

# Track weekly wishlist changes
week_ago <- as.Date("2024-01-15") - 7
wishlists_prev <- vgi_wishlists_by_date(as.character(week_ago))

# Calculate weekly growth
growth <- merge(wishlists, wishlists_prev, 
               by = "steamAppId", 
               suffixes = c("_now", "_prev"))
growth$weekly_change <- growth$wishlistCount_now - growth$wishlistCount_prev
growth$weekly_pct <- (growth$weekly_change / growth$wishlistCount_prev) * 100

# Find fastest growing games
min_wishlists <- 1000  # Only games with substantial wishlists
qualified <- growth[growth$wishlistCount_prev >= min_wishlists, ]
fastest_growing <- head(qualified[order(-qualified$weekly_pct), ], 20)

cat("Fastest growing games (>1000 wishlists):\n")
print(fastest_growing[, c("steamAppId", "wishlistCount_now", 
                         "weekly_change", "weekly_pct")])

# Analyze wishlist distribution
hist(log10(wishlists$wishlistCount + 1),
     breaks = 30,
     main = "Distribution of Wishlist Counts (log scale)",
     xlab = "Log10(Wishlist Count + 1)",
     col = "lightgreen")

# Find games losing wishlists
declining <- growth[growth$weekly_change < -100, ]
cat("Games losing 100+ wishlists this week:", nrow(declining), "\n")

# Seasonal analysis (if you have historical data)
# Compare with same date last year
last_year <- as.Date("2024-01-15") - 365
wishlists_ly <- vgi_wishlists_by_date(as.character(last_year))

yoy <- merge(wishlists, wishlists_ly,
            by = "steamAppId",
            suffixes = c("_now", "_lastyear"))
yoy$yoy_growth <- ((yoy$wishlistCount_now - yoy$wishlistCount_lastyear) / 
                  yoy$wishlistCount_lastyear) * 100

# Find games with massive YoY growth
breakout <- yoy[yoy$yoy_growth > 1000 & yoy$wishlistCount_now > 10000, ]
cat("Breakout games (>1000% YoY growth, >10k wishlists):", nrow(breakout), "\n")

## End(Not run)