% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/st_market_metrics.R
\name{st_market_metrics}
\alias{st_market_metrics}
\title{Fetch Aggregate Sensor Tower Market Metrics}
\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{
\item{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"`.}

\item{countries}{Character vector of 2-letter country codes. Use `"WW"` for
worldwide.}

\item{os}{Character scalar. One of `"ios"`, `"android"`, or `"unified"`.}

\item{date_from, date_to}{Date bounds for the query. Accept `Date` objects or
ISO date strings.}

\item{granularity}{Character scalar. One of `"daily"`, `"weekly"`,
`"monthly"`, or `"quarterly"`.}

\item{metrics}{Character vector. One or both of `"revenue"` and `"downloads"`.}

\item{revenue_unit}{Character scalar. `"dollars"` returns revenue in base
currency units. `"cents"` returns revenue in cents.}

\item{shape}{Character scalar. `"long"` returns one row per metric
observation. `"wide"` returns metric columns.}

\item{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.
}
\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.
}
\section{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{
\dontrun{
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"
)
}

}
