st_market_metrics: Fetch Aggregate Sensor Tower Market Metrics

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

Fetch Aggregate Sensor Tower Market Metrics

Description

Tidy facade for market/category revenue and download denominators. This function routes to Sensor Tower's aggregate 'games_breakdown' endpoint through [st_game_summary()] and never approximates market totals by enumerating apps, rankings, top charts, or title cohorts.

Usage

st_market_metrics(
  category,
  countries,
  os,
  date_from,
  date_to,
  granularity = "monthly",
  metrics = c("revenue", "downloads"),
  revenue_unit = c("dollars", "cents"),
  shape = c("long", "wide"),
  auth_token = NULL
)

Arguments

category	Character or numeric vector of Sensor Tower game category IDs. iOS and Android use different category identifiers; pass the appropriate platform category for platform-specific calls, or the full platform basket for 'os = "unified"'.
countries	Character vector of 2-letter country codes. Use '"WW"' for worldwide.
os	Character scalar. One of '"ios"', '"android"', or '"unified"'.
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"'.
metrics	Character vector. One or both of '"revenue"' and '"downloads"'.
revenue_unit	Character scalar. '"dollars"' returns revenue in base currency units. '"cents"' returns revenue in cents.
shape	Character scalar. '"long"' returns one row per metric observation. '"wide"' returns metric columns.
auth_token	Optional Sensor Tower API token. If 'NULL', falls back to 'SENSORTOWER_AUTH_TOKEN'.

Value

If 'shape = "long"', a tibble with columns 'date', 'country', 'category_id', 'os', 'metric', and 'value'. If 'shape = "wide"', a tibble with columns 'date', 'country', 'category_id', 'os', and requested metric columns.

Denominator Safety

Use 'st_market_metrics()' for game category market denominators. Use [st_rankings()], [st_apps()], and custom-field top-chart workflows for discovery, leaderboards, and title cohorts only. True Game IQ subgenre market denominators require a Sensor Tower market-size export or another confirmed aggregate market endpoint.

Examples

## Not run: 
casino_market <- st_market_metrics(
  category = c("7006", "game_casino"),
  countries = "WW",
  os = "unified",
  date_from = "2025-01-01",
  date_to = "2025-12-31",
  granularity = "monthly"
)

## End(Not run)

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