Package 'sensortowerR'

Retrieve metadata and explicitly convert app IDs

Description

Retrieve metadata and explicitly convert app IDs

Usage

st_app(
  data,
  os = NULL,
  fields = NULL,
  target_os = NULL,
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
os	Platform for character IDs. Table inputs carry their own platform.
fields	Optional names of metadata fields to retain, in addition to IDs and app_name. Missing fields are returned as missing values.
target_os	Optional target ID namespace. Unified conversion uses the provider's mapping; conversion to a store expands all mapped regional SKUs.
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble with app metadata and input columns. Conversions include input_app_id and input_os. No name-based ID matching is performed.

---

Fetch app tags

Description

Fetch app tags

Usage

st_app_tags(
  data,
  os = NULL,
  fields = NULL,
  field_categories = NULL,
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
os	Platform for character IDs. Table inputs carry their own platform.
fields	Custom/global field names to retrieve. Supply fields or field_categories.
field_categories	Provider field categories to retrieve.
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble with app_id, os and a tags list-column, retaining raw fields.

---

Find apps or publishers

Description

Find apps or publishers

Usage

st_apps(
  query = NULL,
  filter = NULL,
  os = "unified",
  limit = 100,
  auth_token = NULL
)

st_publishers(query, os = "unified", limit = 100, auth_token = NULL)

Arguments

query	Search term, or NULL when using filter.
filter	A created st_filter object or server filter ID.
os	Platform to search, default unified.
limit	Maximum results. Search supports at most 250; filtered discovery follows cursor pages up to the requested limit.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

An ungrouped tibble with app_id, os, app_name or publisher_id, os, publisher_name. Additional source metadata is retained.

---

Inspect or clear the session cache

Description

Inspect or clear the session cache

Usage

st_cache_info()

st_cache_clear()

Value

st_cache_info() returns entry counts and expiry times in a tibble. st_cache_clear() invisibly returns the number of removed entries.

---

List the bundled platform categories

Description

List the bundled platform categories

Usage

st_categories(os = NULL)

Arguments

os	Optional ios or android filter. NULL returns both.

Value

A tibble with os, category_id and category_name. This is a bundled reference snapshot, not a live guarantee of provider category coverage.

---

Retrieve store chart positions

Description

Retrieve store chart positions

Usage

st_charts(
  os,
  category,
  chart_type,
  date,
  countries = "US",
  limit = 100,
  auth_token = NULL
)

Arguments

os	Platform for character IDs. Table inputs carry their own platform.
category	Store category ID.
chart_type	Provider store-chart identifier, such as topfreeapplications.
date	Chart date.
countries	Country codes, or WW alone. Defaults to WW.
limit	Maximum entries per country, up to the provider's returned chart.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble with app_id, os, country, date, rank, category_id, chart_type.

---

Fetch demographic estimates without averaging platforms

Description

Fetch demographic estimates without averaging platforms

Usage

st_demographics(
  data,
  date_from,
  date_to,
  os = NULL,
  countries = "WW",
  granularity = "quarterly",
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
os	Platform for character IDs. Table inputs carry their own platform.
countries	Country codes, or WW alone. Defaults to WW.
granularity	all_time or quarterly.
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A long tibble retaining source demographic names. Provider shares are labeled provider_share (no implicit rescaling); average ages use years. Store IDs are required; use st_app(target_os = ...) to expand unified IDs.

---

Inspect package and credential availability without network requests

Description

Inspect package and credential availability without network requests

Usage

st_diagnostics()

Value

A one-row tibble. Credential contents are never returned.

---

Low-level facets access

Description

Low-level facets access

Usage

st_facets(params, auth_token = NULL)

Arguments

params	Named query-parameter list. Vectors become comma-separated values.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble of response records, preserving nested values as list-columns. Specialist wrappers provide typed metric schemas; this advanced interface intentionally preserves the provider's fields.

---

Discover custom field values

Description

Discover custom field values

Usage

st_fields(query = NULL, auth_token = NULL)

Arguments

query	Optional field-name search term.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble with name, global and a values list-column.

---

Construct a local filter, then explicitly create it on the server

Description

Construct a local filter, then explicitly create it on the server

Usage

st_filter(
  genre = NULL,
  monetization = NULL,
  publisher = NULL,
  sdk = NULL,
  custom_fields = NULL,
  filter_id = NULL,
  date_from = NULL,
  date_to = NULL,
  combine = c("and", "or")
)

st_filter_create(filter, auth_token = NULL)

## S3 method for class 'st_filter'
print(x, ...)

Arguments

genre, publisher, sdk	Character field values.
monetization	One or more of free, iap, ads, subscription.
custom_fields	Named list of field values, or a list of explicit field records with name, values, global and exclude.
filter_id	Existing server filter ID(s), mutually exclusive with criteria.
date_from, date_to	Optional release-date bounds for Release Date (US).
combine	Combine field predicates using and or or.
filter	A local st_filter object.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.
x	An st_filter object.
...	Unused.

Value

st_filter() returns a local st_filter object without making requests. st_filter_create() returns the same object with verified server IDs. AND sends all fields in one request; OR creates one filter per field. Consumers union OR results by ID. Values inside a field use the provider's semantics.

Examples

# Construction is local. Only st_filter_create() writes to the server.
st_filter(genre = "RPG", publisher = "Supercell", combine = "and")
st_filter(genre = "RPG", publisher = "Supercell", combine = "or")

---

Read a server filter definition

Description

Read a server filter definition

Usage

st_filter_read(filter, auth_token = NULL)

Arguments

filter	A created st_filter or existing server ID.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble of custom field predicates with filter_id provenance.

---

Fetch market sales totals

Description

Fetch market sales totals

Usage

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

Arguments

categories	Game category IDs, as character strings.
os	Platform for character IDs. Table inputs carry their own platform.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
countries	Country codes, or WW alone. Defaults to WW.
granularity	Sales period: daily, weekly, monthly, quarterly.
metrics	Metrics to retrieve: revenue, downloads, dau, wau, mau.
revenue_unit	Revenue in dollars (USD) or cents.
shape	Long (default) or wide output.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A tibble like st_metrics(), with category_id instead of app_id.

---

Fetch sales and active-user time series in a pipeline

Description

Fetch sales and active-user time series in a pipeline

Usage

st_metrics(
  data,
  date_from,
  date_to,
  metrics = c("revenue", "downloads"),
  os = NULL,
  countries = "WW",
  granularity = "daily",
  revenue_unit = c("dollars", "cents"),
  shape = c("long", "wide"),
  errors = c("abort", "partial"),
  cache = FALSE,
  cache_ttl = 300,
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
metrics	Metrics to retrieve: revenue, downloads, dau, wau, mau.
os	Platform for character IDs. Table inputs carry their own platform.
countries	Country codes, or WW alone. Defaults to WW.
granularity	Sales period: daily, weekly, monthly, quarterly.
revenue_unit	Revenue in dollars (USD) or cents.
shape	Long (default) or wide output.
errors	Abort by default; partial returns explicit error rows and warns.
cache	Use the session cache, disabled by default.
cache_ttl	Cache lifetime in seconds, default 300.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Details

DAU, WAU and MAU always use their native day, week and month windows; granularity controls sales only. Dates label period starts; periods starting outside the requested interval are excluded. Audiences are never summed over time. iOS totals are device users; unified totals are platform users, not deduplicated people. Missing components make totals unknown. Unified sales use the unified endpoint including regional SKUs. No fuzzy name matching or platform fallback occurs. Use st_app(target_os = ...) to convert identifiers explicitly. HTTP/schema failures are never no-data.

Value

An ungrouped tibble. Long output contains app_id, os, country, date, metric, value, unit and period. Wide output includes per-metric unit/period columns. Partial mode also includes status, error and endpoint.

Examples

# Empty input returns a typed tibble without authentication or network calls.
apps <- tibble::tibble(app_id = character(), os = character())
apps |>
  st_metrics(date_from = "2026-01-01", date_to = "2026-01-31")

---

Parse or build a Sensor Tower web URL

Description

Parse or build a Sensor Tower web URL

Usage

st_parse_url(url)

st_build_url(params = list(), path = "/top-charts")

Arguments

url	An https app.sensortower.com URL.
params	Named query parameters; credentials are forbidden.
path	Web path, default /top-charts.

Value

st_parse_url() returns one row per parameter (name, value). st_build_url() returns a URL string. Neither function makes requests.

---

Retrieve a publisher's apps

Description

Retrieve a publisher's apps

Usage

st_publisher_apps(
  data,
  os = NULL,
  limit = 10000,
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A publisher tibble with publisher_id and os, or character IDs.
os	Platform for character IDs. Table inputs carry their own platform.
limit	Maximum apps per publisher (default 10000).
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

An app tibble retaining publisher context. Related publishers are not silently included and names are never used to merge IDs.

---

Rank apps or publishers by an explicit measure

Description

Rank apps or publishers by an explicit measure

Usage

st_rankings(
  measure,
  os,
  date_from,
  date_to,
  countries = "WW",
  granularity = "monthly",
  entity = c("app", "publisher"),
  category = "0",
  comparison = c("absolute", "delta", "transformed_delta"),
  limit = 100,
  filter = NULL,
  auth_token = NULL
)

Arguments

measure	revenue, downloads, dau, wau or mau. Publisher rankings support revenue and downloads only.
os	Platform for character IDs. Table inputs carry their own platform.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
countries	Country codes, or WW alone. Defaults to WW.
granularity	Sales period: daily, weekly, monthly, quarterly.
entity	app or publisher.
category	Category ID, default overall (0).
comparison	absolute, delta or transformed_delta.
limit	Maximum entities per country.
filter	Created filter or server ID; supported for app rankings.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Details

Active rankings support weekly, monthly and quarterly periods; MAU does not support weekly. Active rankings cover one period beginning on date_from; date_to must be its last day. Sales may span multiple periods.

Value

A tibble with entity ID, os, country, date, rank, measure, value and unit. Rankings are separate for each requested country.

---

Fetch rating and review metrics

Description

Fetch rating and review metrics

Usage

st_ratings(
  data,
  date_from,
  date_to,
  os = NULL,
  countries = "WW",
  granularity = "daily",
  bundle = c("ratings_incremental", "ratings_cumulative"),
  breakdown = c("app_id", "date"),
  errors = c("abort", "partial"),
  auth_token = NULL
)

st_reviews(
  data,
  date_from,
  date_to,
  os = NULL,
  countries = "WW",
  granularity = "daily",
  breakdown = c("date", "review_rating"),
  languages = NULL,
  review_keywords = NULL,
  review_sentiments = NULL,
  review_tags = NULL,
  search_terms = NULL,
  rating_filters = NULL,
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
os	Platform for character IDs. Table inputs carry their own platform.
countries	Country codes, or WW alone. Defaults to WW.
granularity	Sales period: daily, weekly, monthly, quarterly.
bundle	ratings_incremental or ratings_cumulative.
breakdown	Provider breakdown. Ratings: app_id, app_id/date, region, region/date, app_version. Reviews: review_rating alone or with date, region, language or app_version. Each app is requested separately.
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.
languages, review_keywords, review_sentiments, review_tags, search_terms	Optional review filters.
rating_filters	Optional star ratings (1 through 5).

Value

A long tibble retaining breakdown columns. Counts use count, averages use stars and provider percentages use provider_percentage.

---

Fetch retention curves

Description

Fetch retention curves

Usage

st_retention(
  data,
  date_from,
  date_to,
  os = NULL,
  countries = "WW",
  method = c("facets", "legacy"),
  bundle = c("retention_daily", "retention_weekly", "retention_monthly"),
  granularity = "quarterly",
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
os	Platform for character IDs. Table inputs carry their own platform.
countries	Country codes, or WW alone. Defaults to WW.
method	facets (default) or legacy. Legacy requires store IDs.
bundle	retention_daily, retention_weekly or retention_monthly.
granularity	Legacy aggregation: all_time or quarterly.
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A long tibble. Facets metrics retain provider horizon names; legacy curves include horizon (days since install). Retention units are fractions.

---

Fetch session time series

Description

Fetch session time series

Usage

st_sessions(
  data,
  date_from,
  date_to,
  os = NULL,
  countries = "WW",
  granularity = "monthly",
  time_period = "week",
  metrics = c("session_count", "session_duration", "time_spent"),
  errors = c("abort", "partial"),
  auth_token = NULL
)

Arguments

data	A data frame with character app_id and os columns, or a character ID vector. User columns are retained; collisions get .input.
date_from, date_to	Inclusive dates, as Date or YYYY-MM-DD strings.
os	Platform for character IDs. Table inputs carry their own platform.
countries	Country codes, or WW alone. Defaults to WW.
granularity	Sales period: daily, weekly, monthly, quarterly.
time_period	Native averaging window: day, week or month.
metrics	Session metrics: session_count, session_duration, time_spent, total_session_count, total_time_spent.
errors	Abort by default; partial returns explicit error rows and warns.
auth_token	API token; defaults to SENSORTOWER_AUTH_TOKEN.

Value

A long tibble with explicit seconds, sessions and per-user units; period records the averaging window.

---