| Title: | Interface to 'Sensor Tower' Mobile App Intelligence API |
| Version: | 1.0.0 |
| Description: | Interface to the 'Sensor Tower' API https://app.sensortower.com/api/docs/app_analysis for mobile app analytics and market intelligence. Provides a small, consistent set of functions to retrieve app metadata, publisher information, download and revenue estimates, active user metrics, category rankings, and market trends. Four core verbs ('st_metrics', 'st_rankings', 'st_app'/'st_apps', 'st_filter') cover the common workflows with standardized parameters and tidyverse-friendly output. Supports both iOS and Android app ecosystems with unified data structures for cross-platform analysis. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Imports: | dplyr, glue, httr, httr2, jsonlite, lubridate, openssl, purrr, rlang, stats, stringr, tibble, tidyr, utils |
| Suggests: | gt, gtExtras, knitr, pkgbuild, rcmdcheck, rmarkdown, rhub, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| Author: | Phillip Black [aut, cre] |
| Maintainer: | Phillip Black <pblack@gameeconomistconsulting.com> |
| URL: | https://github.com/econosopher/sensortowerR |
| BugReports: | https://github.com/econosopher/sensortowerR/issues |
| Depends: | R (≥ 4.1.0) |
| NeedsCompilation: | no |
| Packaged: | 2026-04-24 20:57:58 UTC; phillip |
| Repository: | CRAN |
| Date/Publication: | 2026-04-25 09:40:02 UTC |
Metric Mapping for Custom Tags
Description
Maps raw API field names (from entities.custom_tags or aggregate_tags) to cleaner, user-friendly column names.
Usage
METRIC_MAPPING
Format
An object of class character of length 60.
Numeric Metric Patterns
Description
Patterns to identify columns that should be converted to numeric.
Usage
NUMERIC_METRIC_PATTERNS
Format
An object of class character of length 29.
Add Custom Filter Parameters to Query
Description
Internal function to add custom field filter parameters to API query parameters. Handles validation and OS-specific requirements.
Usage
add_custom_filter_params(
query_params,
custom_fields_filter_id = NULL,
custom_tags_mode = NULL,
os = NULL
)
Arguments
query_params |
List. Existing query parameters |
custom_fields_filter_id |
Character. Custom filter ID from Sensor Tower |
custom_tags_mode |
Character. Tag mode for unified OS |
os |
Character. Operating system (ios, android, unified) |
Value
Modified query_params list with custom filter parameters added
Calculate year-over-year growth rates
Description
Helper function to calculate YoY growth rates from the output of st_yoy_metrics
Usage
calculate_yoy_growth(yoy_data, baseline_year = NULL)
Arguments
yoy_data |
Output from st_yoy_metrics |
baseline_year |
The year to use as baseline (default: earliest year) |
Value
A tibble with growth rates relative to baseline year
Create Custom Filter Example
Description
Generates example code for using custom filters with a function
Usage
create_custom_filter_example(function_name, os = "ios")
Arguments
function_name |
Character. Name of the function |
os |
Character. Example OS to use |
Value
Character string with example code
Custom Filter Utilities
Description
Internal functions for handling custom field filters across sensortowerR functions
Example Data for sensortowerR Package
Description
Creates example data structures that mimic the API responses for testing and demonstration purposes without requiring actual API calls.
Usage
example_sensortower_data(type = "app_info", n = 5)
Arguments
type |
Character string specifying the type of example data to create. Options: "app_info", "rankings", "details", "metrics", "publisher_apps", "top_charts", "game_summary" |
n |
Number of example records to generate (default: 5) |
Value
A tibble with example data matching the structure of actual API responses
Examples
# Get example app search results
example_apps <- example_sensortower_data("app_info")
head(example_apps)
# Get example ranking data
example_rankings <- example_sensortower_data("rankings", n = 10)
print(example_rankings)
Extract Custom Filter from URL Parameters
Description
Helper to extract custom filter parameters from parsed URL parameters
Usage
extract_custom_filter_params(params)
Arguments
params |
List. Parameters from st_parse_web_url() |
Value
List with custom_fields_filter_id and custom_tags_mode (or NULLs)
Core Data Fetching Function
Description
A reusable function to handle the common pattern of fetching data from the API. Handles URL building, request execution, error handling, and response processing.
Usage
fetch_data_core(
endpoint,
params,
auth_token,
verbose = FALSE,
enrich_response = TRUE,
processor = process_response
)
Arguments
endpoint |
Character. API endpoint path (e.g. "ios/sales_report_estimates"). |
params |
List. Query parameters. |
auth_token |
Character. API token. |
verbose |
Logical. Whether to print debug messages. |
enrich_response |
Logical. Whether to enrich the response with metadata. |
processor |
Function. Function to process the response. Defaults to process_response. |
Value
A tibble with the results.
Fetch and Unified Data from Platforms
Description
Fetches data from iOS and/or Android and optionally combines them. Handles missing data from one platform gracefully.
Usage
fetch_unified_data(
ios_app_id = NULL,
android_app_id = NULL,
start_date,
end_date,
countries,
date_granularity,
auth_token,
verbose = FALSE,
combine_to_unified = TRUE
)
Arguments
ios_app_id |
Character. iOS App ID. |
android_app_id |
Character. Android App ID. |
start_date |
Date. Start date. |
end_date |
Date. End date. |
countries |
Character vector. Country codes. |
date_granularity |
Character. Granularity. |
auth_token |
Character. API token. |
verbose |
Logical. Verbose output. |
combine_to_unified |
Logical. Whether to sum metrics into a unified view. |
Value
A tibble with columns date, country, revenue, downloads, and optionally platform/app_id.
Custom Filter Helper Functions
Description
Functions to validate, test, and manage Sensor Tower custom field filters
Format ARPU (Average Revenue Per User)
Description
Format ARPU (Average Revenue Per User)
Usage
format_arpu(val, digits = 2)
Arguments
val |
Numeric ARPU value |
digits |
Number of decimal places (default: 2) |
Value
Formatted ARPU string
Examples
format_arpu(5.234) # "$5.23"
format_arpu(0.99) # "$0.99"
Format currency values with appropriate suffixes
Description
Format currency values with appropriate suffixes
Usage
format_currency(val, digits = 2)
Arguments
val |
Numeric value to format as currency |
digits |
Number of digits after decimal for millions/billions (default: 2) |
Value
Formatted currency string
Examples
format_currency(1234567) # "$1.23M"
format_currency(1234567890) # "$1.23B"
format_currency(123) # "$123"
Format download counts with appropriate suffixes
Description
Format download counts with appropriate suffixes
Usage
format_downloads(val)
Arguments
val |
Numeric value to format as downloads |
Value
Formatted download count string
Examples
format_downloads(1234567) # "1.2M"
format_downloads(1234567890) # "1.2B"
Format large numbers with K/M/B suffixes
Description
Format large numbers with K/M/B suffixes
Usage
format_large_number(val, digits = 1, prefix = "")
Arguments
val |
Numeric value to format |
digits |
Number of digits after decimal for millions/billions (default: 1) |
prefix |
Optional prefix (e.g., "$" for currency) |
Value
Formatted string with appropriate suffix
Examples
format_large_number(1234567) # "1.2M"
format_large_number(1234567890) # "1.2B"
format_large_number(1234567, prefix = "$") # "$1.2M"
Format market share as percentage
Description
Format market share as percentage
Usage
format_market_share(val, digits = 1)
Arguments
val |
Numeric value as decimal (0-1 scale) |
digits |
Number of decimal places (default: 1) |
Value
Formatted market share percentage string
Examples
format_market_share(0.234) # "23.4%"
format_market_share(0.05) # "5.0%"
Format percentages
Description
Format percentages
Usage
format_percent(val, digits = 1)
Arguments
val |
Numeric value to format as percentage (0-100 scale) |
digits |
Number of decimal places (default: 1) |
Value
Formatted percentage string
Examples
format_percent(23.456) # "23.5%"
format_percent(0.234, digits = 2) # "0.23%"
Format retention rates
Description
Format retention rates
Usage
format_retention(val, digits = 1)
Arguments
val |
Numeric value as decimal (0-1 scale) |
digits |
Number of decimal places (default: 1) |
Value
Formatted retention percentage string
Examples
format_retention(0.234) # "23.4%"
format_retention(0.85) # "85.0%"
Format user counts (DAU/MAU/WAU)
Description
Format user counts (DAU/MAU/WAU)
Usage
format_users(val)
Arguments
val |
Numeric value to format as user count |
Value
Formatted user count string
Examples
format_users(1234567) # "1.2M"
format_users(1234) # "1.2K"
Formatting Helper Functions
Description
Functions for formatting numeric values in a human-readable way, particularly useful for revenue, download counts, and percentages.
Get Custom Filter Documentation
Description
Returns standardized documentation for custom filter parameters
Usage
get_custom_filter_docs()
Value
Character vector with roxygen2 parameter documentation
Intelligent App ID Cache and Resolution System
Description
Internal functions to manage a persistent cache of app ID mappings, reducing API calls and improving performance.
Usage
.sensortowerR_env
Format
An object of class environment of length 0.
Helper function to look up category names
Description
Helper function to look up category names
Usage
lookup_category_names(category_ids, platform = "ios")
Arguments
category_ids |
Character vector of category IDs |
platform |
Character string. "ios" or "android" |
Value
Character vector of category names
Map Game Summary Field Names
Description
Internal function to map abbreviated API field names to descriptive names.
Usage
map_game_summary_fields(data, os)
Arguments
data |
Tibble. Data with abbreviated field names. |
os |
Character string. Operating system to determine mappings. |
Value
Tibble with descriptive field names.
Process App Details API Response
Description
Internal function to process and enrich app details API responses.
Usage
process_app_details_response(resp, os)
Arguments
resp |
Response object from httr2 |
os |
Operating system |
Value
A processed tibble with app details
Process Game Summary API Response
Description
Internal function to process and enrich game summary API responses.
Usage
process_game_summary_response(resp, os)
Arguments
resp |
List. Raw API response from game summary endpoint. |
os |
Character string. Operating system to determine field mappings. |
Value
A processed tibble with descriptive column names.
Process Category Ranking API Response
Description
Internal function to process and enrich category ranking API responses.
Usage
process_ranking_response(resp, os, category, country, chart_type, date, limit)
Arguments
resp |
Response object from httr2 |
os |
Operating system |
category |
Category ID used in request |
country |
Country code used in request |
chart_type |
Chart type used in request |
date |
Date used in request (may be NULL) |
limit |
Number of results requested |
Value
A processed tibble with ranking data
Defunct Functions In sensortowerR
Description
Legacy entrypoints retained only as defunct stubs for the v1.0.0 transition.
Usage
st_sales_report(...)
st_unified_sales_report(...)
st_batch_metrics(...)
st_smart_metrics(...)
st_top_charts(...)
st_top_publishers(...)
st_category_rankings(...)
st_app_info(...)
st_app_lookup(...)
st_app_details(...)
st_filter_by_date(...)
st_filter_by_genre(...)
st_filter_by_monetization(...)
st_filter_by_publisher(...)
st_filter_by_sdk(...)
st_custom_fields_filter(...)
st_custom_fields_filter_by_id(...)
st_combine_filters(...)
st_create_simple_filter(...)
st_compare_filter_results(...)
st_generate_example_filter_ids(...)
Fetch Active User Metrics with a Tidy Long Output
Description
Lightweight wrapper around [st_batch_metrics()] focused only on active-user metrics ('dau', 'wau', 'mau'). Returns a tidy long-format tibble that is designed for straightforward tidyverse chaining.
Usage
st_active_users(
os,
app_list,
metrics = c("dau", "wau", "mau"),
date_range = list(start_date = Sys.Date() - 90, end_date = Sys.Date() - 1),
countries,
granularity = "monthly",
parallel = FALSE,
verbose = TRUE,
auth_token = NULL,
max_cores = 2
)
Arguments
os |
Character. Required. Operating system: '"ios"', '"android"', or '"unified"'. |
app_list |
List or data frame containing app information. Same formats accepted by [st_batch_metrics()]. |
metrics |
Character vector. Active-user metrics to return. Must be one or more of '"dau"', '"wau"', '"mau"'. Default is all three. |
date_range |
List with 'start_date' and 'end_date'. |
countries |
Character vector of country codes. |
granularity |
Character granularity ('"daily"', '"weekly"', '"monthly"', '"quarterly"'). Default '"monthly"'. |
parallel |
Logical. Whether to use parallel processing. |
verbose |
Logical. Whether to print progress messages. |
auth_token |
Character string. Sensor Tower API token. Defaults to 'SENSORTOWER_AUTH_TOKEN' environment variable. |
max_cores |
Integer. Maximum cores for parallel processing. |
Value
A tibble with columns including 'original_id', 'app_name', 'app_id', 'app_id_type', 'date', 'country', 'metric', and 'value'.
Analyze Custom Filter Performance
Description
Provides a summary analysis of apps matching a custom filter, including top performers, growth metrics, and category breakdown.
Usage
st_analyze_filter(
filter_id,
measure = "DAU",
regions = "US",
top_n = 10,
auth_token = NULL
)
Arguments
filter_id |
Character. The custom fields filter ID to analyze |
measure |
Character. Metric to analyze: "DAU", "revenue", or "units" |
regions |
Character vector. Region codes (default "US") |
top_n |
Integer. Number of top apps to show (default 10) |
auth_token |
Optional. Character string. Your Sensor Tower API token. |
Value
A list containing summary statistics and top apps
Diagnose API Issues
Description
This function helps diagnose common API issues by testing various ID formats and endpoints to determine the best approach for fetching data.
Usage
st_api_diagnostics(
app_id,
verbose = TRUE,
auth_token = Sys.getenv("SENSORTOWER_AUTH_TOKEN")
)
Arguments
app_id |
Character string. The app ID to diagnose (can be unified, iOS, or Android) |
verbose |
Logical. Show detailed diagnostic output. Default is TRUE. |
auth_token |
Character string. Your Sensor Tower API authentication token. |
Value
A list with diagnostic results including: - 'id_type': Detected ID type - 'platform_ids': Resolved platform-specific IDs - 'endpoint_results': Results from testing various endpoints - 'recommendations': Suggested approach for this app
Examples
## Not run:
# Diagnose Star Trek Fleet Command
diagnosis <- st_api_diagnostics("5ba4585f539ce75b97db6bcb")
# Check iOS app
diagnosis <- st_api_diagnostics("1427744264")
## End(Not run)
Fetch App Details
Description
Thin v1.0.0 facade for app metadata lookups. By default it dispatches to the legacy detailed app metadata endpoint. When 'fields' is supplied, it dispatches to 'st_app_enriched()' and optionally subsets to the requested fields.
Usage
st_app(app_id, os = "unified", fields = NULL, auth_token = NULL)
Arguments
app_id |
Character scalar or vector of app identifiers. |
os |
Operating system context. One of '"ios"', '"android"', or '"unified"'. |
fields |
Optional character vector of enriched fields to keep. When supplied, the request is routed through 'st_app_enriched()'. |
auth_token |
Optional Sensor Tower API token. |
Value
A tibble returned by the dispatched legacy implementation.
Examples
## Not run:
st_app("553834731", os = "ios")
st_app(
c("553834731", "com.supercell.clashofclans"),
fields = c("revenue_90d_ww", "downloads_30d_ww")
)
## End(Not run)
Fetch Enriched Metrics for Specific Apps
Description
Retrieves comprehensive metrics including retention, MAU, DAU, demographics, and other aggregate tags for specific apps by their unified app IDs.
Usage
st_app_enriched(
unified_app_ids,
os = "unified",
regions = "WW",
auth_token = NULL
)
Arguments
unified_app_ids |
Character vector. One or more unified app IDs (24-character hex strings). Required. Use 'st_app_info()' to find these. |
os |
Character string. Operating system context for the request. Must be "unified" (default), "ios", or "android". |
regions |
Character vector. Region codes for data filtering. Defaults to "WW" (worldwide). |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable SENSORTOWER_AUTH_TOKEN. |
Details
This function is designed for the common workflow of: 1. Search for apps by name using 'st_app_info()' 2. Get their unified IDs 3. Fetch enriched metrics for those specific apps using this function
Value
A [tibble][tibble::tibble] with enriched metrics including: - **Identification**: 'unified_app_id', 'unified_app_name' - **Active Users**: 'dau_30d_us', 'dau_30d_ww', 'wau_4w_us', 'wau_4w_ww', 'mau_month_us', 'mau_month_ww' - **Retention**: 'retention_1d_us/ww', 'retention_7d_us/ww', 'retention_14d_us/ww', 'retention_30d_us/ww', 'retention_60d_us/ww' - **Demographics**: 'genders_us', 'genders_ww', 'age_us', 'age_ww', 'male_share_us', 'female_share_us' - **Revenue/Downloads**: 'revenue_30d_ww', 'revenue_90d_ww', 'revenue_alltime_us/ww', 'downloads_30d_ww', 'downloads_alltime_us/ww' - **Monetization**: 'rpd_alltime_us/ww', 'arpu_90d_us/ww' - **Launch**: 'release_date_us/ww', 'earliest_release_date'
Recommended Workflow
“' # Step 1: Search for apps by name apps <- st_app_info("Royal Match")
# Step 2: Get unified IDs app_ids <- apps$unified_app_id
# Step 3: Fetch enriched metrics metrics <- st_app_enriched(app_ids) “'
Data Availability Notes
- **IMPORTANT: Geographic Limitations** - All enriched metrics are only available for **US market ('_us' suffix)** and **Worldwide aggregates ('_ww' suffix)**. Per-country data (e.g., GB, DE, FR, JP) is NOT available through this endpoint. For per-country data, use [st_sales_report()] for revenue/downloads or [st_batch_metrics()] for MAU/DAU time-series. - Retention data (D1, D7, D14, D30, D60) is aggregated for the "last quarter" - not time-series data. D90 retention is NOT available through the API. - Demographics (age/gender) are primarily available for US market only. - Not all metrics are available for all apps - smaller apps may have NA values. - This returns **snapshot data**, not time-series. For historical trends, use [st_batch_metrics()] or [st_sales_report()].
See Also
[st_app_info()] for searching apps by name, [st_app_lookup()] for resolving app IDs, [st_sales_report()] for time-series revenue/download data, [st_batch_metrics()] for time-series DAU/WAU/MAU data
Examples
## Not run:
# Get enriched data for specific apps
royal_match <- st_app_info("Royal Match")
enriched <- st_app_enriched(royal_match$unified_app_id)
# Get data for multiple apps at once
game_ids <- c("5f16a8019f7b275235017614", "660af7c66237390ce7c829fc")
multi_enriched <- st_app_enriched(game_ids)
# View retention metrics
multi_enriched %>%
select(unified_app_name, starts_with("retention"))
## End(Not run)
Fetch Apps by Custom Fields and Tags
Description
Retrieves apps filtered by custom fields and tags from Sensor Tower. This function uses the /v1/app_tag/apps endpoint.
Usage
st_app_tag(
app_id_type,
custom_fields_filter_id,
name = NULL,
value = NULL,
global = TRUE,
last_known_id = NULL,
auth_token = NULL,
base_url = "https://api.sensortower.com"
)
Arguments
app_id_type |
Character string. Operating System. Must be one of "itunes" (iOS) or "unified". Required. |
custom_fields_filter_id |
Character string. ID of a Sensor Tower custom field filter. Required. Use the filter ID from relevant endpoint. |
name |
Optional. Character string. Name of Custom or Global Field. Defaults to "Stock Ticker". |
value |
Optional. Character string. Tag value for custom or global field provided. Leave blank to fetch all possible apps. |
global |
Optional. Logical. Filter by global or organization custom fields. Defaults to TRUE (false means organization custom fields). |
last_known_id |
Optional. Character string. Supply last_known_id from previous request to get next page. Leave blank to get first page. |
auth_token |
Optional. Character string. Your Sensor Tower API token. |
base_url |
Optional. Character string. The base URL for the API. |
Value
A [tibble][tibble::tibble] with app data including IDs and metadata.
Search or Filter Apps
Description
Thin v1.0.0 facade for app discovery by query string or server-side filter.
Usage
st_apps(
query = NULL,
filter = NULL,
os = "ios",
country = "US",
limit = 100,
auth_token = NULL
)
Arguments
query |
Optional search string for app-name search. |
filter |
Optional 'st_filter' object or 24-character filter ID string. |
os |
Operating system context for query searches. |
country |
Two-letter country code used by the filtered-app workflow. |
limit |
Positive integer row limit. |
auth_token |
Optional Sensor Tower API token. |
Value
A tibble returned by the dispatched legacy implementation.
Examples
## Not run:
st_apps(query = "Royal Match", os = "unified", limit = 25)
filt <- st_filter(genre = "Puzzle")
st_apps(filter = filt, country = "US", limit = 50)
## End(Not run)
Batch Look up app information
Description
This function takes a vector of unified app IDs and returns a single data frame containing the corresponding unified_app_id, app_name, platform-specific IDs (ios_app_id, android_app_id), and icon_url. It handles chunking requests to the st_app_details endpoint (limit 100).
Usage
st_batch_app_lookup(
app_ids,
auth_token = Sys.getenv("SENSORTOWER_AUTH_TOKEN"),
verbose = FALSE
)
Arguments
app_ids |
Character vector of unified app IDs. |
auth_token |
Character string. Your Sensor Tower API authentication token. |
verbose |
Logical. Whether to show progress messages. Default is FALSE. |
Value
A tibble with columns:
-
unified_app_id: The Sensor Tower unified app ID -
app_name: The app's display name -
ios_app_id: iOS app ID if found -
android_app_id: Android app ID if found -
icon_url: URL of the app icon
Returns empty tibble if no apps can be found or details cannot be fetched.
Examples
## Not run:
# Look up multiple games
apps <- st_batch_app_lookup(c("5ba4585f539ce75b97db6bcb", "5d10d6bfecb4db5f93902f23"))
## End(Not run)
Build Sensor Tower Filter URL
Description
Constructs a URL for the Sensor Tower web interface where you can create custom filters. Visit this URL, configure your filters, and then copy the custom_fields_filter_id from the resulting URL.
Usage
st_build_filter_url(
os = "unified",
category = NULL,
countries = NULL,
base_url = "https://app.sensortower.com/top-charts"
)
Arguments
os |
Character string. Operating system filter. One of "ios", "android", or "unified". Defaults to "unified". |
category |
Optional. Category ID to pre-select. |
countries |
Optional. Character vector of country codes to pre-select. |
base_url |
Character string. Base URL for Sensor Tower. Defaults to "https://app.sensortower.com/top-charts". |
Value
Character string. The constructed URL.
Examples
## Not run:
# Build URL for iOS games in US
url <- st_build_filter_url(os = "ios", category = 6014, countries = "US")
# Open in browser
browseURL(url)
## End(Not run)
Create Sensor Tower Web URL from Parameters
Description
Builds a Sensor Tower web interface URL from API parameters. This is the reverse of st_parse_web_url().
Usage
st_build_web_url(
os = "unified",
measure = "revenue",
category = NULL,
regions = "US",
start_date = NULL,
end_date = NULL,
custom_fields_filter_id = NULL,
custom_tags_mode = NULL,
...
)
Arguments
os |
Operating system |
measure |
Measure type |
category |
Category ID |
regions |
Region codes (converted to country parameters) |
start_date |
Start date |
end_date |
End date |
custom_fields_filter_id |
Custom filter ID |
custom_tags_mode |
Custom tags mode |
... |
Additional parameters |
Value
Character string URL
Show App ID Cache Statistics
Description
Display information about the current app ID cache
Usage
st_cache_info()
Value
No return value, called for side effects (displaying cache statistics).
List Available Sensor Tower Categories
Description
Returns a tibble of app categories recognized by the Sensor Tower API, mapping category IDs to category names for different platforms (iOS/Android). Useful for finding valid inputs for the 'category' parameter in other functions.
Usage
st_categories(platform = NULL)
Arguments
platform |
Optional character string. Filter results for a specific platform ("ios" or "android"). If NULL (default), returns categories for both platforms. |
Value
A tibble with columns 'platform' (character, "ios" or "android"), 'category_id' (character, e.g., "6014"), and 'category_name' (character, e.g., "Games").
Examples
# Get all categories
all_cats <- st_categories()
head(all_cats)
# Get only iOS categories
ios_cats <- st_categories(platform = "ios")
head(ios_cats)
# Find game categories on iOS
ios_games <- subset(st_categories("ios"), grepl("Game", category_name))
head(ios_games)
Clear App Name Cache
Description
Clears the internal cache of app name lookups. Useful for testing or when you want to refresh app name data.
Usage
st_clear_app_cache()
Value
No return value, called for side effects (clearing the cache).
Clear App ID Cache
Description
Clears the in-memory and on-disk cache of app ID mappings
Usage
st_clear_id_cache(disk = TRUE)
Arguments
disk |
Logical. Also remove the on-disk cache file (default TRUE). |
Value
No return value, called for side effects (clearing the cache).
Custom Fields Filter Functions
Description
Functions to work with Sensor Tower custom fields filters.
Custom Fields Utility Functions
Description
Utility functions for common custom fields filtering scenarios in Sensor Tower. These functions provide pre-built filters for frequently used queries.
Get Custom Fields Values
Description
Retrieves a list of all accessible custom fields and their possible values. This is useful for discovering what custom fields are available to filter by.
Usage
st_custom_fields_values(
term = NULL,
auth_token = NULL,
base_url = "https://api.sensortower.com"
)
Arguments
term |
Optional. Character string. Search term to filter field names. |
auth_token |
Optional. Character string. Your Sensor Tower API token. |
base_url |
Optional. Character string. The base URL for the API. |
Value
A tibble containing custom fields and their possible values
Examples
## Not run:
# Get all custom fields
fields <- st_custom_fields_values()
# Search for specific fields
date_fields <- st_custom_fields_values(term = "date")
## End(Not run)
Custom Fields Filter Workflow Helper Functions
Description
Helper functions to streamline working with custom fields filters in Sensor Tower. These functions combine the custom fields endpoints with data retrieval functions to provide a complete workflow.
Fetch Demographics Data for Apps
Description
Retrieves user demographics (age and gender breakdown) for specific apps from the Sensor Tower Usage Intelligence API. This function queries the demographics endpoint directly using platform-specific app IDs.
Usage
st_demographics(
unified_app_id = NULL,
ios_app_id = NULL,
android_app_id = NULL,
os = NULL,
country = "US",
date_granularity = "all_time",
start_date = NULL,
end_date = NULL,
auth_token = NULL,
verbose = TRUE
)
Arguments
unified_app_id |
Character string. Sensor Tower unified app ID (24-character hex). Will be resolved to platform-specific IDs automatically. |
ios_app_id |
Character string. iOS app ID (numeric, e.g., "1234567890"). |
android_app_id |
Character string. Android package name (e.g., "com.example.app"). |
os |
Character string. Operating system: "ios" or "android". Required if using platform-specific IDs. When using unified_app_id, defaults to trying both platforms. |
country |
Character string. Country code (e.g., "US", "GB"). Default is "US". Only single country supported per request. |
date_granularity |
Character string. Either "all_time" (default) or "quarterly". All-time data goes back to Q4 2015. Quarterly data begins Q1 2021. |
start_date |
Date or character string. Start date for quarterly data in "YYYY-MM-DD" format. Ignored for all_time granularity. |
end_date |
Date or character string. End date for quarterly data in "YYYY-MM-DD" format. Ignored for all_time granularity. |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable SENSORTOWER_AUTH_TOKEN. |
verbose |
Logical. If TRUE, prints progress messages. |
Value
A [tibble][tibble::tibble] with demographics metrics including: - **app_id**: The platform-specific app ID - **os**: Platform (ios or android) - **country**: Country code - **female_percent**: Percentage of female users (0-100) - **male_percent**: Percentage of male users (0-100) - **average_age**: Average user age - **age_13_17**, **age_18_24**, **age_25_34**, **age_35_44**, **age_45_54**, **age_55_64**, **age_65_plus**: Age group percentages - **confidence**: Data confidence level
Data Availability
- Quarterly data begins Q1 2021 - All-time data goes back to Q4 2015 - Demographics are primarily available for US market - Data availability depends on app's user base size
Recommended Workflow
“' # Step 1: Search for app by name app <- st_app_info("Royal Match")
# Step 2: Get demographics using unified ID demographics <- st_demographics(unified_app_id = app$unified_app_id[1]) “'
See Also
[st_app_info()] for searching apps by name, [st_app_lookup()] for resolving app IDs, [st_retention()] for retention metrics
Examples
## Not run:
# Get demographics for an app using unified ID
demo <- st_demographics(unified_app_id = "5f16a8019f7b275235017614")
# Get demographics for iOS app directly
demo <- st_demographics(
ios_app_id = "553834731",
os = "ios",
country = "US"
)
## End(Not run)
Discover Available Custom Fields
Description
Searches and displays available custom fields that can be used for filtering. This is helpful for discovering what fields are available before creating filters.
Usage
st_discover_fields(search_term = NULL, show_values = FALSE, auth_token = NULL)
Arguments
search_term |
Optional. Character string to search for in field names |
show_values |
Logical. Whether to show possible values for each field |
auth_token |
Optional. Character string. Your Sensor Tower API token. |
Value
A tibble with custom fields information
Examples
## Not run:
# Find all game-related fields
game_fields <- st_discover_fields("game")
# Find all date fields
date_fields <- st_discover_fields("date")
# Show all fields with their values
all_fields <- st_discover_fields(show_values = TRUE)
## End(Not run)
Extract Filter ID from Sensor Tower URL
Description
Extracts the custom_fields_filter_id parameter from a Sensor Tower URL. This is helpful when copying URLs from the web interface.
Usage
st_extract_filter_id(url)
Arguments
url |
Character string. A Sensor Tower URL containing custom_fields_filter_id |
Value
Character string. The extracted filter ID, or NULL if not found.
Examples
## Not run:
url <- "https://app.sensortower.com/top-charts?custom_fields_filter_id=687df26ac5a19ebcfe817d7f"
filter_id <- st_extract_filter_id(url)
## End(Not run)
Extract All Parameters from Sensor Tower URL
Description
Extracts and displays all parameters from a Sensor Tower web URL in a readable format. Useful for understanding complex URLs.
Usage
st_extract_url_params(url)
Arguments
url |
Character string. A Sensor Tower web interface URL |
Value
Data frame with parameter names and values
Examples
## Not run:
url <- "https://app.sensortower.com/market-analysis/top-apps?os=unified&measure=DAU"
params_df <- st_extract_url_params(url)
View(params_df)
## End(Not run)
Low-Level Access to Sensor Tower Facets Metrics
Description
Performs a GET request against Sensor Tower's '"/v1/facets/metrics"' route. This helper stays intentionally low-level so package code can work with new facets-based endpoints while higher-level wrappers are added incrementally.
Usage
st_facets_metrics(
query = character(),
params = list(),
auth_token = NULL,
host = c("api", "app"),
verbose = FALSE
)
Arguments
query |
Character vector of raw query fragments appended verbatim after encoded 'params'. This is useful when Sensor Tower documents nested or repeated parameters that are awkward to express as a regular named R list. Example: 'c("filters[app_ids][]=553834731")'. |
params |
Named list of regular query parameters. Vector values are serialized as comma-separated strings to match Sensor Tower's 'style=form, explode=false' usage in the OpenAPI spec. |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable 'SENSORTOWER_AUTH_TOKEN'. |
host |
Character string. Which host to target: '"api"' (default) or '"app"'. The 'app' host uses 'https://app.sensortower.com/api'. |
verbose |
Logical. If 'TRUE', prints the request URL with the auth token redacted. |
Details
As of March 17, 2026, the facets route is live and the retention contract is validated against production. The machine-readable Sensor Tower docs remain gated behind a signed-in web session, so this helper still provides a stable escape hatch for raw or partially documented facets requests.
Value
A parsed JSON response. Rectangular top-level responses are returned as a tibble; nested responses are returned as a named list.
Examples
## Not run:
# Retention request using regular query parameters
response <- st_facets_metrics(
params = list(
facets = "retention",
bundle = "retention_daily",
breakdown = c("date", "app_id"),
start_date = "2025-01-01",
end_date = "2025-01-31",
app_ids = "553834731"
)
)
## End(Not run)
Create a Sensor Tower Filter Object
Description
Thin v1.0.0 facade for building or wrapping Sensor Tower custom-field filter IDs. When criteria are supplied, the function translates them into the legacy custom-fields request structure and creates a server-side filter ID using the existing implementation.
Usage
st_filter(
date_from = NULL,
date_to = NULL,
genre = NULL,
monetization = NULL,
publisher = NULL,
sdk = NULL,
custom_fields = NULL,
filter_id = NULL,
combine = c("and", "or"),
auth_token = NULL
)
## S3 method for class 'st_filter'
print(x, ...)
## S3 method for class 'st_filter'
format(x, ...)
## S3 method for class 'st_filter'
as.character(x, ...)
## S3 method for class 'st_filter'
c(..., recursive = FALSE, combine = c("and", "or"))
Arguments
date_from, date_to |
Optional date bounds for a release-date criterion. |
genre |
Optional character vector of game genres. |
monetization |
Optional monetization criteria. Accept either a character vector such as 'c("free", "iap")' or a named list like 'list(free = TRUE, iap = TRUE)'. |
publisher |
Optional character vector of publisher names. |
sdk |
Optional character vector of SDK names. |
custom_fields |
Optional raw custom-fields specification. Can be a list-of-lists already matching the legacy request format or a named list of field names and values. |
filter_id |
Optional existing 24-character Sensor Tower filter ID to wrap. |
combine |
Logical operator metadata for multi-criterion filters: '"and"' or '"or"'. |
auth_token |
Optional Sensor Tower API token. |
x |
An 'st_filter' object (S3 method argument). |
... |
Additional arguments. For 'c.st_filter()', further 'st_filter' objects to combine; ignored by 'print.st_filter()', 'format.st_filter()', and 'as.character.st_filter()'. |
recursive |
Unused; present for S3 method-signature compatibility with [base::c()]. |
Value
An object of class 'st_filter', implemented as a list with elements: - 'criteria': normalized criteria supplied to 'st_filter()' - 'combine': '"and"' or '"or"' - 'filter_id': the wrapped or created server-side filter ID
Examples
## Not run:
st_filter(genre = c("Puzzle", "Strategy"))
st_filter(
date_from = "2024-01-01",
date_to = "2024-12-31",
monetization = c("free", "iap")
)
existing <- st_filter(filter_id = "687df26ac5a19ebcfe817d7f")
as.character(existing)
## End(Not run)
Fetch Game Market Summary Data
Description
Retrieves aggregated download and revenue estimates by game categories, countries, and date ranges. This provides a market overview of game performance across different segments.
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 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 - **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)
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**: 'cc' = Country Code, 'd' = Date, 'aid' = App ID
iPhone and iPad data are automatically combined for simplified analysis.
See Also
[st_categories()], [st_top_charts()], [st_metrics()]
Examples
## Not run:
# Basic game market summary (last 30 days, worldwide)
game_summary <- st_game_summary()
# Specific categories and countries
rpg_summary <- st_game_summary(
categories = c(7001, 7002),
countries = c("US", "GB", "DE"),
date_granularity = "weekly"
)
# 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)
Get App Names from Publisher Apps Result
Description
Helper function to create a name lookup table from the result of 'st_publisher_apps()'. This handles canonical ID mapping automatically, so you can join sales data (which uses canonical IDs) back to app names.
Usage
st_get_app_names(apps_df, include_canonical = TRUE)
Arguments
apps_df |
A tibble returned by 'st_publisher_apps()'. |
include_canonical |
Logical. If TRUE, includes mappings for canonical IDs that were resolved during aggregation. Defaults to TRUE. |
Value
A tibble with columns 'unified_app_id' and 'app_name' suitable for joining with sales data or other API results.
Examples
## Not run:
# Get apps with canonical ID resolution
apps <- st_publisher_apps("647eb849d9d91f31a54f1792", aggregate_related = TRUE)
# Get name lookup table
name_lookup <- st_get_app_names(apps)
# Use with sales data
sales <- st_unified_sales_report(apps$unified_app_id, ...)
sales_with_names <- sales %>%
left_join(name_lookup, by = "unified_app_id")
## End(Not run)
Get Pre-Built Filter Collections
Description
Returns commonly used filter IDs for quick access to pre-defined app segments.
Usage
st_get_filter_collection(
collection = c("top_genres", "monetization_models", "platform_exclusive",
"market_segments"),
auth_token = NULL
)
Arguments
collection |
Character. Name of the collection: - "top_genres": Major game genres - "monetization_models": Different monetization approaches - "platform_exclusive": Platform-specific apps - "market_segments": Market segment filters |
auth_token |
Optional. Character string. Your Sensor Tower API token. |
Value
A named list of filter IDs
Examples
## Not run:
# Get filter IDs for top game genres
genre_filters <- st_get_filter_collection("top_genres")
# Use a filter from the collection
puzzle_apps <- st_get_filtered_apps(
filter_id = genre_filters$puzzle,
measure = "DAU",
regions = "US"
)
## End(Not run)
Get Top Apps with Custom Filter
Description
Retrieves top apps using a custom fields filter. This combines filter creation with data retrieval in a single workflow.
Usage
st_get_filtered_apps(
field_name = NULL,
field_values = NULL,
filter_id = NULL,
measure = "DAU",
regions = "US",
date = NULL,
end_date = NULL,
limit = 100,
enrich_response = TRUE,
auth_token = NULL,
...
)
Arguments
field_name |
Character. Name of the custom field to filter by (or NULL to use filter_id) |
field_values |
Character vector. Values to filter for (or NULL to use filter_id) |
filter_id |
Character. Existing filter ID to use (alternative to field_name/values) |
measure |
Character. Metric to measure: "DAU", "WAU", "MAU", "revenue", or "units" |
regions |
Character vector. Region codes (e.g., "US", "WW") |
date |
Character or Date. Start date for the query |
end_date |
Optional. Character or Date. End date for the query |
limit |
Integer. Maximum number of apps to return (default 100) |
enrich_response |
Logical. Whether to enrich with additional metrics |
auth_token |
Optional. Character string. Your Sensor Tower API token. |
... |
Additional parameters passed to st_top_charts |
Value
A tibble with top apps data
Examples
## Not run:
# Get top Word games by DAU
word_games <- st_get_filtered_apps(
field_name = "Game Sub-genre",
field_values = "Word",
measure = "DAU",
regions = "US",
limit = 20
)
# Use existing filter ID
apps <- st_get_filtered_apps(
filter_id = "603697f4241bc16eb8570d37",
measure = "revenue",
regions = "US"
)
## End(Not run)
Get Unified ID Mapping for Apps
Description
Retrieves the mapping between platform-specific app IDs and unified app IDs. This function handles cases where platform IDs from st_top_charts may not be directly searchable, using app names as a fallback resolution method.
Usage
st_get_unified_mapping(
app_ids,
app_names = NULL,
os = "unified",
auth_token = Sys.getenv("SENSORTOWER_AUTH_TOKEN")
)
Arguments
app_ids |
Character vector of app IDs (can be iOS, Android, or unified hex IDs) |
app_names |
Character vector of app names (optional, helps with resolution) |
os |
Character string. Operating system: "ios", "android", or "unified" |
auth_token |
Character string. Sensor Tower API authentication token. Defaults to environment variable SENSORTOWER_AUTH_TOKEN. |
Details
This function uses an ID-first approach (no name-based resolution): 1. For hex IDs (24-char), uses st_app_lookup to get platform IDs 2. For platform IDs, first tries to look them up via st_app_lookup 3. If direct lookup fails, searches the unified index using the platform ID as the term and matches exact IDs within nested ios_apps/android_apps 4. Returns the best available mapping for each app using IDs only
Note: Platform IDs from st_top_charts may be regional or legacy IDs that aren't directly searchable. In these cases, name-based search provides the most reliable resolution to unified IDs.
Value
A data frame with columns: - 'input_id': The original ID provided - 'unified_app_id': The unified app ID (hex format) - 'unified_app_name': The unified app name - 'ios_app_id': iOS app ID (if available) - 'android_app_id': Android app ID (if available) - 'publisher_id': Publisher ID - 'publisher_name': Publisher name
Examples
## Not run:
# Get mapping with app names for better resolution
mapping <- st_get_unified_mapping(
app_ids = c("943599237", "com.bandainamcogames.dbzdokkan"),
app_names = c("Dragon Ball Z Dokkan Battle", "Dragon Ball Z Dokkan Battle"),
os = "unified"
)
## End(Not run)
Create FiveThirtyEight-styled GT Dashboard from Top Charts Data
Description
Creates a professional, FiveThirtyEight-themed GT table dashboard from Sensor Tower top charts data with customizable styling and metric options.
Usage
st_gt_dashboard(
data,
title = "Top Mobile Games",
subtitle = NULL,
ranking_metric = "revenue_180d_ww",
show_demographics = TRUE,
show_engagement = TRUE,
show_retention = TRUE,
retention_region = "us",
show_rpd = TRUE,
bar_charts = TRUE,
bar_chart_columns = NULL,
heatmap_retention = TRUE,
compact_mode = TRUE,
width = 1800,
height = 700,
save_path = NULL,
icon_cache_dir = "inst/images/app_icons",
raw = FALSE,
color_scheme = list(revenue = "#FF6600", downloads = "#008FD5", engagement = "#9C27B0",
rpd = "#4CAF50", retention_low = "#FFCDD2", retention_mid = "#C8E6C9", retention_high
= "#4CAF50")
)
Arguments
data |
Data frame from st_top_charts() or similar Sensor Tower function |
title |
Character string for the table title (default: "Top Mobile Games") |
subtitle |
Character string for subtitle. If NULL, auto-generates based on data |
ranking_metric |
Character string specifying which metric to use for ranking. Options: "revenue_180d_ww", "revenue_30d_ww", "downloads_180d_ww", "downloads_30d_ww", etc. (default: "revenue_180d_ww") |
show_demographics |
Logical, whether to show demographic columns (age, gender) (default: TRUE) |
show_engagement |
Logical, whether to show engagement metrics (DAU, WAU, MAU) (default: TRUE) |
show_retention |
Logical, whether to show retention metrics (default: TRUE) |
retention_region |
Character string for retention region ("us", "ww", etc.) (default: "us") |
show_rpd |
Logical, whether to show Revenue Per Download (default: TRUE) |
bar_charts |
Logical, whether to show bar chart visualizations (default: TRUE) |
bar_chart_columns |
Character vector of column patterns to add bar charts to. If NULL, applies to all numeric columns except RPD and retention. |
heatmap_retention |
Logical, whether to apply heatmap to retention columns (default: TRUE) |
compact_mode |
Logical, whether to use compact row heights (default: TRUE) |
width |
Numeric, table width in pixels (default: 1800) |
height |
Numeric, table height in pixels (default: 700) |
save_path |
Character string, path to save the table image. If NULL, returns GT object |
icon_cache_dir |
Character string, directory to cache app icons (default: "inst/images/app_icons") |
raw |
Logical, whether to return a minimally styled table without custom formatting, bar charts, or heatmaps (default: FALSE) |
color_scheme |
List with color codes for different metric types: - revenue: Revenue metrics color (default: "#FF6600") - downloads: Downloads metrics color (default: "#008FD5") - engagement: Engagement metrics color (default: "#9C27B0") - rpd: RPD metrics color (default: "#4CAF50") - retention_low: Low retention color (default: "#FFCDD2") - retention_mid: Mid retention color (default: "#C8E6C9") - retention_high: High retention color (default: "#4CAF50") |
Value
GT object (if save_path is NULL) or saves image and returns path
Examples
## Not run:
# Basic usage - one line after st_top_charts()
top_rpgs <- st_top_charts(category = 7014, measure = "revenue")
st_gt_dashboard(top_rpgs)
# Raw mode for minimal styling
st_gt_dashboard(top_rpgs, raw = TRUE)
# Customize the dashboard
st_gt_dashboard(
top_rpgs,
title = "Top Role-Playing Games Q4 2024",
ranking_metric = "revenue_30d_ww",
show_retention = FALSE,
save_path = "dashboard.png"
)
# Change color scheme
st_gt_dashboard(
top_rpgs,
color_scheme = list(
revenue = "#E74C3C",
downloads = "#3498DB",
engagement = "#9B59B6"
)
)
## End(Not run)
Validate Custom Field Filter ID Format
Description
Checks if a filter ID matches the expected 24-character hexadecimal format used by Sensor Tower.
Usage
st_is_valid_filter_id(filter_id)
Arguments
filter_id |
Character string. The filter ID to validate |
Value
Logical. TRUE if valid format, FALSE otherwise
Examples
## Not run:
# Valid filter ID
st_is_valid_filter_id("687df26ac5a19ebcfe817d7f") # TRUE
# Invalid filter IDs
st_is_valid_filter_id("invalid") # FALSE
st_is_valid_filter_id("687df26ac5a19ebcfe817d7") # FALSE (too short)
## End(Not run)
Fetch Sensor Tower Metrics
Description
Thin v1.0.0 facade for sales/download metrics. The function validates a standardized argument set, dispatches to the legacy implementation that best matches the request, and then normalizes the result into a stable schema.
Usage
st_metrics(
app_id,
metrics = c("revenue", "downloads"),
os = "unified",
countries = "WW",
date_from = Sys.Date() - 90,
date_to = Sys.Date(),
granularity = "daily",
revenue_unit = c("dollars", "cents"),
shape = c("long", "wide"),
cache = TRUE,
auth_token = NULL
)
Arguments
app_id |
Character scalar or vector of app identifiers. Each entry can be a Sensor Tower unified app ID, an iOS numeric app ID, or an Android package name. |
metrics |
Character vector of metrics to return. Supported values are '"revenue"' and '"downloads"'. |
os |
Character scalar. One of '"ios"', '"android"', or '"unified"'. |
countries |
Character vector of 2-letter country codes. Use '"WW"' for worldwide aggregates. |
date_from, date_to |
Date bounds for the query. Accept 'Date' objects or ISO date strings. |
granularity |
Character scalar. One of '"daily"', '"weekly"', '"monthly"', or '"quarterly"'. |
revenue_unit |
Character scalar. '"dollars"' (default) returns revenue in base currency units. '"cents"' returns revenue in cents for compatibility with the legacy API surface. |
shape |
Character scalar. '"long"' returns one row per metric observation. '"wide"' returns one row per app/date/country with separate metric columns. |
cache |
Logical. If 'TRUE', use a process-local cache keyed on the normalized arguments. |
auth_token |
Optional Sensor Tower API token. If 'NULL', falls back to 'SENSORTOWER_AUTH_TOKEN'. |
Value
If 'shape = "long"', a tibble with columns: - 'app_id': identifier supplied to 'st_metrics()' - 'os': normalized operating system - 'country': 2-letter country code - 'date': observation date - 'metric': one of '"revenue"' or '"downloads"' - 'value': metric value; revenue is in dollars by default and cents when 'revenue_unit = "cents"'
If 'shape = "wide"', a tibble with columns: - 'app_id' - 'os' - 'country' - 'date' - one numeric column per requested metric
Examples
## Not run:
st_metrics(
app_id = "553834731",
os = "ios",
countries = "US",
date_from = Sys.Date() - 30,
date_to = Sys.Date() - 1
)
st_metrics(
app_id = c("553834731", "com.supercell.clashofclans"),
os = "unified",
shape = "wide",
countries = c("US", "GB"),
revenue_unit = "cents"
)
## End(Not run)
Parse Sensor Tower Web URL to API Parameters
Description
Converts a Sensor Tower web interface URL into API-compatible parameters that can be used with sensortowerR functions. This is helpful when you want to replicate a web query in R.
Usage
st_parse_web_url(url, verbose = TRUE)
Arguments
url |
Character string. A Sensor Tower web interface URL |
verbose |
Logical. Whether to print parameter mapping details. Defaults to TRUE. |
Value
List of API-compatible parameters suitable for use with st_top_charts() and other sensortowerR functions
Examples
## Not run:
# Parse a web URL
url <- "https://app.sensortower.com/market-analysis/top-apps?os=unified&measure=DAU"
params <- st_parse_web_url(url)
# Use the parameters in an API call
data <- do.call(st_top_charts, params)
# Or modify parameters before using
params$limit <- 50
data <- do.call(st_top_charts, params)
## End(Not run)
Get All Apps from a Publisher
Description
Retrieves a list of apps associated with a specified unified publisher ID from the Sensor Tower API. Targets the '/v1/unified/publishers/apps' endpoint.
Usage
st_publisher_apps(
unified_id = NULL,
publisher_id = NULL,
aggregate_related = FALSE,
auth_token = Sys.getenv("SENSORTOWER_AUTH_TOKEN"),
verbose = TRUE
)
Arguments
unified_id |
Character. Unified ID to resolve apps for. May be either: - Unified Publisher ID (24-char hex) - Unified App ID (24-char hex) belonging to a publisher The API returns the unified publisher and all associated apps in both cases. |
publisher_id |
Deprecated alias for 'unified_id'. |
aggregate_related |
Logical. If TRUE, ensures each app's unified_app_id is the canonical ID that aggregates ALL regional SKUs. This solves the problem where games like "Watcher of Realms" are published under multiple regional publishers (Moonton, Vizta Games, Skystone Games, etc.) and may return different unified_app_ids. When TRUE, the function looks up each app by name to find the true unified_app_id that combines all regional versions. Defaults to FALSE for backwards compatibility. |
auth_token |
Character. Your Sensor Tower API authentication token. Defaults to the value stored in the 'SENSORTOWER_AUTH_TOKEN' environment variable. |
verbose |
Logical. If TRUE, prints progress messages during aggregation. Defaults to TRUE. |
Value
A [tibble][tibble::tibble] containing details of the apps associated with the publisher. The exact columns depend on the API response but often include app IDs, names, platform, etc. Returns an empty tibble if the publisher ID is invalid, has no apps, or an error occurs.
Solving Regional Publisher Issues
Many publishers have regional subsidiaries or partners that publish the same game under different app IDs in different regions. For example, Moonton's "Watcher of Realms" is published by Moonton in some regions, Vizta Games in others, and Skystone Games in others.
When 'aggregate_related = TRUE', this function ensures you get the unified_app_id that represents the FULL game across all regional publishers, which is required for accurate revenue/download aggregation via 'st_unified_sales_report()'.
API Endpoint Used
- 'GET /v1/unified/publishers/apps'
Examples
## Not run:
# Ensure SENSORTOWER_AUTH_TOKEN is set in your environment
# Sys.setenv(SENSORTOWER_AUTH_TOKEN = "your_secure_auth_token_here")
# Basic usage - get publisher's apps
apps_list <- st_publisher_apps(unified_id = "647eb849d9d91f31a54f1792")
# With regional SKU aggregation - ensures canonical unified_app_ids
apps_list <- st_publisher_apps(
unified_id = "647eb849d9d91f31a54f1792",
aggregate_related = TRUE
)
# Then use with st_unified_sales_report() for accurate data
sales <- st_unified_sales_report(
unified_app_id = apps_list$unified_app_id,
countries = "WW",
start_date = "2024-01-01",
end_date = "2024-12-31",
date_granularity = "monthly"
)
## End(Not run)
Publisher Portfolio Analysis
Description
Fetches comprehensive portfolio data for a publisher including revenue, downloads, MAU, and rankings. Returns a tidy data frame ready for visualization or GT table creation.
Usage
st_publisher_portfolio(
publisher = NULL,
publisher_id = NULL,
start_date = "2023-01-01",
end_date = NULL,
countries = "WW",
metrics = c("revenue", "downloads", "mau"),
include_rankings = TRUE,
include_portfolio_total = TRUE,
granularity = "yearly",
min_revenue = 1e+05,
auth_token = Sys.getenv("SENSORTOWER_AUTH_TOKEN"),
verbose = TRUE,
use_cache = FALSE,
cache_dir = NULL
)
Arguments
publisher |
Character. Publisher name to search for (e.g., "Lilith Games", "Supercell", "King"). The function will search for the publisher and use the first match. |
publisher_id |
Character. Optional. If provided, skips the publisher search and uses this unified_publisher_id directly. |
start_date |
Date or character. Start date for metrics (default: "2023-01-01"). |
end_date |
Date or character. End date for metrics (default: last day of previous month). |
countries |
Character. Countries for metrics (default: "WW" for worldwide). |
metrics |
Character vector. Which metrics to fetch. Options: "revenue", "downloads", "mau". Default: all three. |
include_rankings |
Logical. Whether to fetch subgenre rankings from top charts. Default: TRUE. |
include_portfolio_total |
Logical. Whether to add a portfolio total row. Default: TRUE. |
granularity |
Character. How to aggregate the data: "yearly" (default), "quarterly", or "monthly". |
min_revenue |
Numeric. Minimum revenue threshold to include an app. Default: 100000 (apps with at least $100K in any year). |
auth_token |
Character. Sensor Tower API token. Defaults to SENSORTOWER_AUTH_TOKEN environment variable |
verbose |
Logical. Print progress messages. Default: TRUE. |
use_cache |
Logical. Use cached data if available. Default: FALSE. When TRUE, requires cache_dir to be specified. |
cache_dir |
Character. Directory for cached data. Default: NULL (no caching). Must be explicitly set to enable caching. Use tempdir() for temporary caching. |
Value
A tibble with portfolio data including: - app_name: Game name - subgenre: Game sub-genre - subgenre_rank: Rank within sub-genre - revenue_{year}: Revenue by year - downloads_{year}: Downloads by year - mau_{year}: Average MAU by year (if requested) - revenue_yoy, downloads_yoy, mau_yoy: Year-over-year growth percentages
Examples
## Not run:
# Simple usage - just provide publisher name
lilith_portfolio <- st_publisher_portfolio("Lilith Games")
# Piped workflow
library(dplyr)
"Supercell" %>%
st_publisher_portfolio(
start_date = "2023-01-01",
metrics = c("revenue", "downloads")
) %>%
filter(revenue_2024 > 1000000) %>%
arrange(desc(revenue_2024))
# Custom date range and countries
portfolio <- st_publisher_portfolio(
publisher = "King",
start_date = "2022-01-01",
end_date = "2024-12-31",
countries = c("US", "GB", "DE"),
metrics = c("revenue", "downloads", "mau"),
include_rankings = TRUE
)
## End(Not run)
Fetch Sensor Tower Rankings
Description
Thin v1.0.0 facade that standardizes the app, publisher, and category ranking entrypoints while dispatching to the existing implementations.
Usage
st_rankings(
entity = c("app", "publisher", "category"),
os = "ios",
category = NULL,
country = "US",
chart_type = "topfreeapplications",
date = Sys.Date() - 1,
limit = 100,
filter = NULL,
auth_token = NULL
)
Arguments
entity |
Ranking entity to fetch: '"app"', '"publisher"', or '"category"'. |
os |
Operating system. One of '"ios"', '"android"', or '"unified"'. |
category |
Optional category identifier forwarded to the legacy ranking implementation. |
country |
Two-letter country code. |
chart_type |
Chart type for category rankings. Ignored for app and publisher rankings. |
date |
Ranking date. Accepts a 'Date' object or ISO date string. |
limit |
Positive integer row limit. |
filter |
Optional 'st_filter' object or 24-character filter ID string. |
auth_token |
Optional Sensor Tower API token. |
Value
A tibble with standardized columns 'rank', 'id', 'name', 'os', 'category', 'country', and 'date', plus any entity-specific columns returned by the dispatched implementation.
Examples
## Not run:
st_rankings(entity = "app", os = "ios", category = 6014, country = "US")
st_rankings(
entity = "category",
os = "android",
category = "game",
chart_type = "topgrossing",
country = "GB"
)
## End(Not run)
Fetch Rating Metrics from Sensor Tower's Facets API
Description
Retrieves rating metrics from Sensor Tower's new facets-based ratings endpoint. This wrapper targets '"/v1/facets/metrics?facets=ratings"' and returns a tidy tibble with the live response columns preserved.
Usage
st_ratings_facets(
app_ids,
bundle = c("ratings_incremental", "ratings_cumulative"),
breakdown = c("app_id", "date"),
start_date,
end_date,
date_granularity = NULL,
regions = NULL,
android_localized_estimates = TRUE,
auth_token = NULL,
verbose = FALSE
)
Arguments
app_ids |
Character vector of iOS app IDs or Android package names. Sensor Tower documents a maximum of 1,000 IDs per request. |
bundle |
Character string. Rating bundle to request: '"ratings_incremental"' or '"ratings_cumulative"'. |
breakdown |
Breakdown fields or a comma-separated breakdown string. Supported combinations are '"app_id"', '"app_id,date"', '"region"', '"region,date"', and '"app_version"'. |
start_date |
Start date in 'YYYY-MM-DD' format or as 'Date'. |
end_date |
End date in 'YYYY-MM-DD' format or as 'Date'. |
date_granularity |
Optional date granularity. Required when 'breakdown' includes 'date'. |
regions |
Optional character vector of region codes. |
android_localized_estimates |
Logical. Whether to apply Android country weighting. Defaults to 'TRUE' to match the current documented default. |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable 'SENSORTOWER_AUTH_TOKEN'. |
verbose |
Logical. If 'TRUE', prints the request URL with the auth token redacted. |
Details
Validated against the live Sensor Tower API on March 17, 2026.
Value
A [tibble][tibble::tibble] containing rating metrics such as 'rating_average_incremental', 'rating_count_incremental', or their cumulative counterparts.
See Also
[st_facets_metrics()] for raw facets access
Examples
## Not run:
ratings <- st_ratings_facets(
app_ids = "553834731",
bundle = "ratings_incremental",
breakdown = c("app_id", "date"),
start_date = "2024-01-01",
end_date = "2024-01-07",
date_granularity = "day"
)
## End(Not run)
Fetch Retention Data for Apps
Description
Retrieves retention metrics (D1-D90) for specific apps from the Sensor Tower Usage Intelligence API. This function queries the retention endpoint directly using platform-specific app IDs.
Usage
st_retention(
unified_app_id = NULL,
ios_app_id = NULL,
android_app_id = NULL,
os = NULL,
country = "US",
date_granularity = "all_time",
start_date = NULL,
end_date = NULL,
auth_token = NULL,
verbose = TRUE
)
Arguments
unified_app_id |
Character string. Sensor Tower unified app ID (24-character hex). Will be resolved to platform-specific IDs automatically. |
ios_app_id |
Character string. iOS app ID (numeric, e.g., "1234567890"). |
android_app_id |
Character string. Android package name (e.g., "com.example.app"). |
os |
Character string. Operating system: "ios" or "android". Required if using platform-specific IDs. When using unified_app_id, defaults to "ios" but will try both platforms. |
country |
Character string. Country code (e.g., "US", "GB"). Default is "US". Only single country supported per request. |
date_granularity |
Character string. Either "all_time" (default) or "quarterly". All-time data goes back to Q4 2015. Quarterly data begins Q1 2021. |
start_date |
Date or character string. Start date for quarterly data in "YYYY-MM-DD" format. Ignored for all_time granularity. |
end_date |
Date or character string. End date for quarterly data in "YYYY-MM-DD" format. Ignored for all_time granularity. |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable SENSORTOWER_AUTH_TOKEN. |
verbose |
Logical. If TRUE, prints progress messages. |
Value
A [tibble][tibble::tibble] with retention metrics including: - **app_id**: The platform-specific app ID - **os**: Platform (ios or android) - **country**: Country code - **retention_d1** through **retention_d90**: Retention percentages (0-1 scale) - **confidence**: Data confidence level (red=low, yellow=medium, green=high) - **baseline_downloads**: Total downloads in baseline period - **baseline_start_date**, **baseline_end_date**: Dates for baseline period
Data Availability
- Quarterly data begins Q1 2021 - All-time data goes back to Q4 2015 - Data is only available for apps with sufficient user base - Confidence levels: red (<=3), yellow (4-6), green (>=7)
Recommended Workflow
“' # Step 1: Search for app by name app <- st_app_info("Royal Match")
# Step 2: Get retention data using unified ID retention <- st_retention(unified_app_id = app$unified_app_id[1]) “'
See Also
[st_app_info()] for searching apps by name, [st_app_lookup()] for resolving app IDs, [st_demographics()] for user demographics data
Examples
## Not run:
# Get retention for an app using unified ID
retention <- st_retention(unified_app_id = "5f16a8019f7b275235017614")
# Get retention for iOS app directly
retention <- st_retention(
ios_app_id = "553834731",
os = "ios",
country = "US"
)
# Get quarterly retention data
retention <- st_retention(
unified_app_id = "5f16a8019f7b275235017614",
date_granularity = "quarterly",
start_date = "2024-01-01",
end_date = "2024-09-30"
)
## End(Not run)
Fetch Retention Metrics from Sensor Tower's Facets API
Description
Retrieves retention curves from Sensor Tower's new facets-based retention endpoint. This wrapper targets '"/v1/facets/metrics?facets=retention"' and returns a tidy tibble with the live response columns preserved.
Usage
st_retention_facets(
app_ids = NULL,
unified_app_ids = NULL,
bundle = c("retention_daily", "retention_weekly", "retention_monthly"),
breakdown = c("date", "app_id"),
start_date,
end_date,
regions = NULL,
auth_token = NULL,
verbose = FALSE
)
Arguments
app_ids |
Character vector of platform-specific app IDs. May contain iOS numeric IDs or Android bundle IDs. Supply exactly one of 'app_ids' or 'unified_app_ids'. |
unified_app_ids |
Character vector of Sensor Tower unified app IDs. Supply exactly one of 'app_ids' or 'unified_app_ids'. |
bundle |
Character string. Retention bundle to request: '"retention_daily"', '"retention_weekly"', or '"retention_monthly"'. |
breakdown |
Character vector of breakdown fields. Supported combinations are the ones documented by Sensor Tower: '"date"', '"app_id"', '"unified_app_id"', '"date,app_id"', '"date,unified_app_id"', '"unified_app_id,app_id"', and '"date,unified_app_id,app_id"'. |
start_date |
Start date in 'YYYY-MM-DD' format or as 'Date'. |
end_date |
End date in 'YYYY-MM-DD' format or as 'Date'. |
regions |
Optional character vector of region codes. When omitted, Sensor Tower returns worldwide estimates. |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable 'SENSORTOWER_AUTH_TOKEN'. |
verbose |
Logical. If 'TRUE', prints the request URL with the auth token redacted. |
Details
Validated against the live Sensor Tower API on March 17, 2026. The production response currently returns daily retention columns including 'est_retention_d14' and 'est_retention_d365'.
Value
A [tibble][tibble::tibble] with one row per requested breakdown combination. The response preserves Sensor Tower's live metric column names such as 'est_retention_d1', 'est_retention_d14', 'est_retention_w52', or 'est_retention_m12'.
See Also
[st_retention()] for the legacy retention endpoint, [st_facets_metrics()] for raw facets access
Examples
## Not run:
retention <- st_retention_facets(
app_ids = "553834731",
bundle = "retention_daily",
breakdown = c("date", "app_id"),
start_date = "2025-01-01",
end_date = "2025-01-31"
)
## End(Not run)
Fetch Review Metrics by Rating from Sensor Tower's Facets API
Description
Retrieves review metrics broken down by star rating from Sensor Tower's new facets-based review endpoint. This wrapper targets '"/v1/facets/metrics?facets=reviews_by_rating"'.
Usage
st_reviews_by_rating_facets(
app_id,
breakdown = c("date", "review_rating"),
start_date,
end_date,
date_granularity = NULL,
regions = NULL,
languages = NULL,
review_keywords = NULL,
review_sentiments = NULL,
review_tags = NULL,
search_terms = NULL,
rating_filters = NULL,
auth_token = NULL,
verbose = FALSE
)
Arguments
app_id |
Single iOS app ID or Android package name. |
breakdown |
Breakdown fields or a comma-separated breakdown string. Supported combinations are '"review_rating"', '"date,review_rating"', '"region,review_rating"', '"language,review_rating"', and '"app_version,review_rating"'. |
start_date |
Start date in 'YYYY-MM-DD' format or as 'Date'. |
end_date |
End date in 'YYYY-MM-DD' format or as 'Date'. |
date_granularity |
Optional date granularity. Required when 'breakdown' includes 'date'. |
regions |
Optional character vector of iOS region codes. |
languages |
Optional character vector of Android language codes. |
review_keywords |
Optional character vector of review-keyword filters. |
review_sentiments |
Optional character vector of sentiment filters. |
review_tags |
Optional character vector of review-tag filters. |
search_terms |
Optional character vector of content search terms. |
rating_filters |
Optional character vector or integer vector of star filters ('1' through '5'). |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable 'SENSORTOWER_AUTH_TOKEN'. |
verbose |
Logical. If 'TRUE', prints the request URL with the auth token redacted. |
Details
Validated against the live Sensor Tower API on March 17, 2026.
Value
A [tibble][tibble::tibble] containing fields such as 'review_rating', 'review_rating_count', 'review_rating_percentage', and 'review_rating_average'.
See Also
[st_facets_metrics()] for raw facets access
Examples
## Not run:
reviews <- st_reviews_by_rating_facets(
app_id = "553834731",
breakdown = c("date", "review_rating"),
start_date = "2024-01-01",
end_date = "2024-01-07",
date_granularity = "day",
regions = "US"
)
## End(Not run)
Fetch Session Metrics Time Series Data
Description
Retrieves session metrics time series data (session count, session duration, time spent) for apps from the Sensor Tower Usage Intelligence API.
Usage
st_session_metrics(
unified_app_id = NULL,
ios_app_id = NULL,
android_app_id = NULL,
start_date,
end_date,
metrics = c("session_count", "session_duration", "time_spent"),
regions = "US",
time_period = "week",
date_granularity = "monthly",
os = NULL,
breakdown = "unified_app_id",
auth_token = NULL,
verbose = TRUE
)
Arguments
unified_app_id |
Character string or vector. Sensor Tower unified app ID(s) (24-character hex). Maximum 100 apps per request. |
ios_app_id |
Character string or vector. iOS app ID(s) for non-unified queries. |
android_app_id |
Character string or vector. Android package name(s) for non-unified queries. |
start_date |
Date or character string. Start date in "YYYY-MM-DD" format. Data is available from 2021-01-01 onward. |
end_date |
Date or character string. End date in "YYYY-MM-DD" format. |
metrics |
Character vector. Metrics to retrieve. Options include: - "time_spent" (average seconds per user per day) - "total_time_spent" (total seconds across all users) - "session_duration" (average session length in seconds) - "session_count" (average sessions per user per day) - "total_session_count" (total sessions across all users) Default is c("session_count", "session_duration", "time_spent"). |
regions |
Character vector. Region/country codes (e.g., "US", "GB"). Default is "US". Use NULL for all regions. |
time_period |
Character string. Session metrics time period. Options: "day", "week". Default is "week". Returns averaged session metrics for each period within a month. |
date_granularity |
Character string. Aggregate data by granularity. Options: "daily", "weekly", "monthly". Default is "monthly". Note: "daily" granularity may not be supported by the API for all apps; use "weekly" or "monthly" if you receive empty results with "daily". |
os |
Character string. Filter by platform for unified apps. Options: "ios", "android", or NULL for both. Default is NULL. |
breakdown |
Character string. Fields for data aggregation. Options: "unified_app_id", "app_id", "region". Default is "unified_app_id". |
auth_token |
Character string. Your Sensor Tower API token. Defaults to environment variable SENSORTOWER_AUTH_TOKEN. |
verbose |
Logical. If TRUE, prints progress messages. |
Value
A [tibble][tibble::tibble] with session metrics including: - **unified_app_id** or **app_id**: The app identifier - **date**: Date of the data point - **time_spent**: Average seconds spent per user per day - **total_time_spent**: Total seconds across all users - **session_duration**: Average session length in seconds - **session_count**: Average sessions per user per day - **total_session_count**: Total session count across all users
Data Availability
- Data is available from 2021-01-01 onward - Session metrics require Usage Intelligence subscription - Maximum 100 apps per request
See Also
[st_retention()] for retention metrics, [st_demographics()] for user demographics, [st_batch_metrics()] for MAU/DAU/WAU metrics
Examples
## Not run:
# Get session metrics for a unified app
sessions <- st_session_metrics(
unified_app_id = "5fbc3849d0b8414136857afc",
start_date = "2024-01-01",
end_date = "2024-12-01"
)
# Get specific metrics with weekly granularity
sessions <- st_session_metrics(
unified_app_id = "5fbc3849d0b8414136857afc",
start_date = "2024-01-01",
end_date = "2024-03-01",
metrics = c("session_count", "session_duration"),
date_granularity = "weekly"
)
# Get session data for Android app directly
sessions <- st_session_metrics(
android_app_id = "com.example.app",
start_date = "2024-01-01",
end_date = "2024-06-01"
)
## End(Not run)
Test a Custom Filter ID
Description
Tests whether a custom filter ID works with the Sensor Tower API by making a minimal test request. This helps verify that the filter exists and is accessible with your authentication.
Usage
st_test_filter(filter_id, os = "ios", verbose = TRUE, auth_token = NULL)
Arguments
filter_id |
Character string. The filter ID to test |
os |
Character string. Operating system to test with. One of "ios", "android", or "unified". Defaults to "ios". |
verbose |
Logical. Whether to print detailed test results. Defaults to TRUE. |
auth_token |
Optional. Character string. Your Sensor Tower API token. Defaults to environment variable SENSORTOWER_AUTH_TOKEN. |
Value
List with test results including success status and any error messages
Examples
## Not run:
# Test a filter ID
result <- st_test_filter("687df26ac5a19ebcfe817d7f")
# Test silently
result <- st_test_filter("687df26ac5a19ebcfe817d7f", verbose = FALSE)
# Test with different OS
result <- st_test_filter("687df26ac5a19ebcfe817d7f", os = "unified")
## End(Not run)
Year-over-Year Metrics Comparison
Description
Fetches metrics for the same date range across multiple years for year-over-year comparisons. Allows flexible date ranges and supports all available metrics including revenue, downloads, and active users.
Usage
st_yoy_metrics(
os,
unified_app_id = NULL,
ios_app_id = NULL,
android_app_id = NULL,
publisher_id = NULL,
years = NULL,
period_start,
period_end,
metrics = c("revenue", "downloads"),
countries,
cache_dir = NULL,
auth_token = Sys.getenv("SENSORTOWER_AUTH_TOKEN"),
verbose = TRUE,
granularity,
use_single_fetch = TRUE
)
Arguments
os |
Character. Required. Operating system: "ios", "android", or "unified". This determines which platform's data is returned. |
unified_app_id |
Character vector. Sensor Tower unified app ID(s). Must be 24-character hex format (e.g., "5ba4585f539ce75b97db6bcb"). |
ios_app_id |
Character vector. iOS app ID(s) (e.g., "1234567890"). |
android_app_id |
Character vector. Android package name(s) (e.g., "com.example.app"). |
publisher_id |
Character vector. Publisher ID(s) (alternative to app IDs). |
years |
Integer vector. Years to compare (e.g., c(2022, 2023, 2024)). If NULL, uses current year and previous year. |
period_start |
Character string or Date. Start of the comparison period. Can be "MM-DD" format (e.g., "01-01" for Jan 1) or a full date. If a full date is provided, only the month and day are used. |
period_end |
Character string or Date. End of the comparison period. Can be "MM-DD" format (e.g., "03-31" for Mar 31) or a full date. If a full date is provided, only the month and day are used. |
metrics |
Character vector. Metrics to fetch. Supports "revenue", "downloads", "dau", "wau", and "mau". Default is both revenue and downloads. |
countries |
Character vector. Country codes (e.g., "US", "GB", "JP"). Required. |
cache_dir |
Character. Directory for caching API responses (optional). |
auth_token |
Character string. Sensor Tower API token. |
verbose |
Logical. Print progress messages. |
granularity |
Character. Date granularity for the data (e.g., "daily", "monthly"). |
use_single_fetch |
Logical. If TRUE, uses a single API call to fetch all data. Defaults to TRUE for efficiency. |
Details
This function is designed for year-over-year comparisons:
- **Flexible date ranges**: Compare any period (e.g., Q1, specific months, custom ranges) - **Multiple years**: Compare across 2+ years in a single call - **Smart date handling**: Automatically handles leap years and invalid dates - **YoY calculations**: Includes both percentage and absolute change - **Caching**: Reuses cached data to minimize API calls
The function will apply the same calendar period (month/day range) to each specified year, making it easy to compare seasonal trends, campaign periods, or any custom date range across years.
Value
A tibble in tidy/long format with columns: - 'app_id': The app ID used for fetching data - 'app_id_type': Type of app ID ("ios", "android", or "unified") - 'entity_id': App or publisher ID - 'entity_name': App or publisher name - 'entity_type': "app" or "publisher" - 'year': Year of the data - 'date_start': Start date of the period (YYYY-MM-DD) - 'date_end': End date of the period (YYYY-MM-DD) - 'country': Country code - 'metric': The metric name (e.g., "revenue", "downloads", "dau") - 'value': Metric value (units depend on metric type) - 'yoy_change': Year-over-year change (percentage) - 'yoy_change_absolute': Year-over-year change (absolute value)
Examples
## Not run:
# Compare Q1 performance across years
q1_comparison <- st_yoy_metrics(
os = "ios",
ios_app_id = "553834731", # Candy Crush iOS
years = c(2022, 2023, 2024),
period_start = "01-01",
period_end = "03-31",
countries = "US",
metrics = c("revenue", "downloads")
)
# Compare holiday season (Nov-Dec) across years
holiday_comparison <- st_yoy_metrics(
os = "unified",
unified_app_id = "5ba4585f539ce75b97db6bcb",
years = c(2021, 2022, 2023),
period_start = "11-01",
period_end = "12-31",
countries = c("US", "GB", "JP"),
metrics = c("revenue", "downloads", "dau")
)
# Compare specific campaign period using full dates
campaign_comparison <- st_yoy_metrics(
os = "android",
android_app_id = "com.king.candycrushsaga",
years = NULL, # Uses current and previous year
period_start = as.Date("2024-02-14"), # Valentine's campaign
period_end = as.Date("2024-02-28"),
countries = c("US", "GB", "JP"),
metrics = c("revenue", "downloads", "dau", "wau")
)
## End(Not run)
Standardize Revenue Units Across sensortowerR
Description
Ensures revenue values have consistent units across all sensortowerR functions. The Sensor Tower API returns revenue in cents, but for consistency with other functions like st_sales_report, this converts to base currency units.
Usage
standardize_revenue_units(data, source = "unknown", target_unit = "base")
Arguments
data |
Data frame containing revenue columns |
source |
Character string indicating the data source |
target_unit |
Character string: "base" (dollars/euros/etc) or "cents" |
Details
The Sensor Tower API inconsistently returns revenue values: - Top Charts API: revenue in cents - Sales Report API: revenue in base currency units - Publishers API: revenue in cents (but converts to base units)
This function ensures consistency by converting all revenue to base units by default, while preserving the original values for reference.
Value
Data frame with standardized revenue values
Validate Custom Filter Parameters
Description
Checks if custom filter parameters are valid before making API call
Usage
validate_custom_filter_params(
custom_fields_filter_id = NULL,
custom_tags_mode = NULL,
os = NULL,
require_category = TRUE,
category = NULL
)
Arguments
custom_fields_filter_id |
Character. Custom filter ID |
custom_tags_mode |
Character. Tag mode |
os |
Character. Operating system |
require_category |
Logical. Whether category is required when no filter |
category |
Category parameter value |
Value
NULL if valid, stops with error if invalid