st_ratings_facets: Fetch Rating Metrics from Sensor Tower's Facets API

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

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)

sensortowerR documentation built on March 18, 2026, 5:07 p.m.