st_game_summary: Fetch Game Market Summary Data

In sensortowerR: Interface to 'Sensor Tower' Mobile App Intelligence API

Fetch Game Market Summary Data

Description

Retrieves aggregate download and revenue estimates by game categories, countries, and date ranges from Sensor Tower's 'games_breakdown' endpoint. Use this for market/category denominator series; do not approximate market totals by batching top charts, rankings, or large app rosters.

Usage

st_game_summary(
  categories = 7001,
  countries,
  os,
  date_granularity,
  start_date,
  end_date,
  auth_token = NULL,
  base_url = "https://api.sensortower.com",
  enrich_response = TRUE
)

Arguments

categories	Character string or numeric vector. Game category IDs to analyze. Defaults to 7001 (a popular game category). Use 'st_categories()' to find valid category IDs.
countries	Character vector or comma-separated string. Country codes (e.g., '"US"', 'c("US", "GB")', '"WW"' for worldwide) to analyze. Required.
os	Character string. Operating System. Must be one of "ios", "android", or "unified". Required. Note: The underlying API only supports "ios" and "android"; when 'os = "unified"' this function automatically fetches both platforms and combines them into a single table with total columns.
date_granularity	Character string. Time granularity for aggregation. Must be one of "daily", "weekly", "monthly", or "quarterly". Required.
start_date	Character string or Date object. Start date for the query in "YYYY-MM-DD" format. Required.
end_date	Character string or Date object. End date for the query in "YYYY-MM-DD" format, inclusive. Required.
auth_token	Optional. Character string. Your Sensor Tower API token.
base_url	Optional. Character string. The base URL for the API.
enrich_response	Optional. Logical. If 'TRUE' (default), enriches the response with readable column names and processes the data.

Value

A [tibble][tibble::tibble] with aggregate game market summary data including: - **Category information**: Game category details - **Geographic data**: Country-level breakdowns - **Downloads**: iOS (iPhone + iPad combined) and Android download estimates - **Revenue**: iOS (iPhone + iPad combined) and Android revenue estimates, expressed in dollars when 'enrich_response = TRUE' - **Totals (unified only)**: 'Total Downloads', 'Total Revenue' - **Time series**: Data broken down by specified granularity

**Automatic Data Combination**: For iOS and unified platforms, iPhone and iPad data are automatically combined into single "iOS Downloads" and "iOS Revenue" columns for simplified analysis.

API Endpoint Used

- **Game Summary**: 'GET /v1/{os}/games_breakdown' (API only supports 'os = "ios"' or 'os = "android"'; unified is synthesized)

Revenue Units

The raw 'games_breakdown' endpoint returns revenue in cents. With 'enrich_response = TRUE', this function converts revenue fields to dollars before combining devices or platforms. With 'enrich_response = FALSE', raw endpoint fields are returned unchanged.

Field Mappings and Processing

The API returns abbreviated field names which are automatically mapped to descriptive names and processed: - **iOS**: 'iu' + 'au' = iOS Downloads (combined), 'ir' + 'ar' = iOS Revenue (combined) - **Android**: 'u' = Android Downloads, 'r' = Android Revenue - **Common**: 'ca' = Category, 'cc' = Country Code, 'd' = Date

iPhone and iPad data are automatically combined for simplified analysis. For 'os = "unified"', iOS and Android aggregate rows are summed by date and country across the requested category basket.

See Also

[st_categories()], [st_rankings()], [st_metrics()]

Examples

## Not run: 
# Specific categories and countries
rpg_summary <- st_game_summary(
  categories = c(7001, 7002),
  countries = c("US", "GB", "DE"),
  os = "ios",
  date_granularity = "weekly",
  start_date = "2024-01-01",
  end_date = "2024-03-31"
)

# Monthly summary for iOS games in the US
ios_monthly <- st_game_summary(
  os = "ios",
  countries = "US", 
  date_granularity = "monthly",
  start_date = "2024-01-01",
  end_date = "2024-06-30"
)

## End(Not run)

sensortowerR documentation built on May 14, 2026, 5:06 p.m.