% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/st_ratings_review_facets.R
\name{st_ratings_facets}
\alias{st_ratings_facets}
\title{Fetch Rating Metrics from Sensor Tower's Facets API}
\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{
\item{app_ids}{Character vector of iOS app IDs or Android package names.
Sensor Tower documents a maximum of 1,000 IDs per request.}

\item{bundle}{Character string. Rating bundle to request:
`"ratings_incremental"` or `"ratings_cumulative"`.}

\item{breakdown}{Breakdown fields or a comma-separated breakdown string.
Supported combinations are `"app_id"`, `"app_id,date"`, `"region"`,
`"region,date"`, and `"app_version"`.}

\item{start_date}{Start date in `YYYY-MM-DD` format or as `Date`.}

\item{end_date}{End date in `YYYY-MM-DD` format or as `Date`.}

\item{date_granularity}{Optional date granularity. Required when
`breakdown` includes `date`.}

\item{regions}{Optional character vector of region codes.}

\item{android_localized_estimates}{Logical. Whether to apply Android country
weighting. Defaults to `TRUE` to match the current documented default.}

\item{auth_token}{Optional. Character string. Your Sensor Tower API token.
Defaults to environment variable `SENSORTOWER_AUTH_TOKEN`.}

\item{verbose}{Logical. If `TRUE`, prints the request URL with the auth token
redacted.}
}
\value{
A [tibble][tibble::tibble] containing rating metrics such as
  `rating_average_incremental`, `rating_count_incremental`, or their
  cumulative counterparts.
}
\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.
}
\details{
Validated against the live Sensor Tower API on March 17, 2026.
}
\examples{
\dontrun{
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"
)
}

}
\seealso{
[st_facets_metrics()] for raw facets access
}
