# Mobile App Reviews Scraper & Version Radar (`ambitious_ross_tj2/mobile-app-reviews-scraper-version-radar`) Actor

Unofficial Apple App Store review scraper. Collect recent public reviews, deduplicate them, and compare ratings across store-version collection cohorts. Not affiliated with Apple Inc.

- **URL**: https://apify.com/ambitious\_ross\_tj2/mobile-app-reviews-scraper-version-radar.md
- **Developed by:** [Local Lead Ops](https://apify.com/ambitious_ross_tj2) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 review returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

**Unofficial Actor. Not affiliated with, endorsed by, or sponsored by Apple Inc.**

Find iPhone and iPad apps by Apple ID or broad search term, collect recent public App Store customer reviews, and flag evidence-backed rating drops between observed app versions. Stable state deduplicates review IDs across successful runs.

Search-friendly use cases include Apple App Store review scraping, iOS app review monitoring, competitor review tracking, release-quality monitoring, version sentiment comparison, and rating regression detection.

### What the Actor returns

Each default-dataset item is one newly observed public review with:

- Apple app ID, app name, storefront, and App Store link;
- rating, title, text, public author display name, review timestamp, and public App Store reviews-page link;
- the current store version reported by Apple's Lookup/Search API;
- the store-version cohort in which the Actor first observed the review, plus accumulated sample counts and average ratings for the current and immediately preceding monitored versions;
- `regression`, `no_regression`, or `insufficient_evidence`, plus the measured rating delta when the configured evidence gate is met.

The run summary and bounded fetch failures are stored in the default key-value store. They are not dataset results.

### Quick start

```json
{
  "searchTerms": ["budget planner", "expense tracker"],
  "appIds": ["284882215"],
  "country": "us",
  "maxApps": 5,
  "searchResultsPerTerm": 5,
  "maxReviewPages": 2,
  "maxReviews": 100,
  "minimumReviewsPerVersion": 5,
  "regressionThreshold": 0.5,
  "stateKey": "weekly-finance-watch"
}
```

Explicit `appIds` are resolved first. Search results then fill the remaining `maxApps` slots in Apple response order, with duplicate app IDs removed. The first successful run emits currently visible reviews up to `maxReviews`; later runs using the same `stateKey` emit only review IDs not already stored. A zero-item repeat run is valid.

### How the regression signal works

Apple's public web review response does not report the reviewer's installed app version. The Actor therefore attributes each newly observed review to the store version reported by Apple's Search/Lookup API during that run. This is collection-cohort attribution, not a claim about the version installed by the reviewer.

For each app, the Actor accumulates rating count and rating sum once for every emitted review ID in that observed store-version cohort. It compares the current store version with the greatest lower, naturally ordered version observed in state. A signal is only classified after both versions reach `minimumReviewsPerVersion`:

- `regression`: current average minus comparison average is at most the negative `regressionThreshold`;
- `no_regression`: both evidence gates are met, but the drop is smaller;
- `insufficient_evidence`: one version is missing or either sample is too small.

This is a deterministic monitoring-cohort comparison, not sentiment AI, causal analysis, anomaly prediction, exact per-review version data, or proof that a release caused a rating change. Meaningful cross-version evidence requires using the same `stateKey` across at least one store-version change.

### Bounded operation and PPE

Inputs cap one run at 20 apps, 5 search terms, 20 search candidates per term, 10 review pages per app, and 1,000 emitted reviews. HTTP responses are capped at 5 MB. The Actor uses only public HTTPS Apple endpoints and needs no secrets, cookies, login, proxy, browser, generative model, or `fal` credential. It runs once and exits; Standby is not used.

The launch hypothesis uses Apify's synthetic `apify-default-dataset-item` event at `$0.0005` per visible review. The code makes exactly one `Actor.push_data()` call for each visible review result and makes no explicit charge call, so every visible default-dataset review maps to one synthetic event. Summary and failure records do not produce dataset-item events. Platform usage and final pricing must match the live Apify Console configuration.

### Public sources

- Apple Search API: `https://itunes.apple.com/search`
- Apple Lookup API: `https://itunes.apple.com/lookup`
- Apple App Store public web review JSON: `https://apps.apple.com/api/apps/v1/catalog/{country}/apps/{appId}/reviews?platform=web&sort=recent&offset={offset}`

### Important limitations

Apple controls the public endpoint availability, search ranking, storefront coverage, review ordering, moderation, localization, fields, and history depth. The public web API is undocumented and can change or stop working without notice; it is a bounded recent sample, not a complete historical export. Some apps/storefronts have no accessible reviews. The review response does not expose reviewer-installed app version, and the reviews-page link may not deep-link to one review. Natural version ordering handles ordinary numeric versions but is not a complete SemVer implementation.

Deduplication is stateful and best-effort across successful runs. It retains at most 5,000 review IDs and 50 version buckets per app. Changing `stateKey`, deleting storage, exceeding retention, or a process interruption between dataset and state writes can allow a review to appear again. Reviews beyond `maxReviews` are not marked seen, so they can appear in a later run.

Public review text and author display names are user-generated content. Follow applicable Apple terms, privacy rules, and downstream platform policies. Do not treat the signal as a release verdict, support priority, market-research guarantee, or substitute for reading the underlying reviews.

### Local tests

From this Actor directory:

```powershell
python -m unittest discover -s tests -v
```

Tests use fixtures only and do not call Apple or Apify.

# Actor input Schema

## `appIds` (type: `array`):

Numeric Apple track IDs. Explicit IDs are considered before search results.

## `searchTerms` (type: `array`):

Broad queries resolved through Apple's public Search API in the selected storefront.

## `country` (type: `string`):

Two-letter Apple storefront country code, such as us, gb, ca, au, or de.

## `maxApps` (type: `integer`):

Hard cap after explicit IDs and search results are deduplicated.

## `searchResultsPerTerm` (type: `integer`):

Maximum Apple Search API candidates requested for each term.

## `maxReviewPages` (type: `integer`):

Maximum 10-review public web API pages requested for each resolved app.

## `maxReviews` (type: `integer`):

Global hard cap on new, visible default-dataset review items for one run.

## `minimumReviewsPerVersion` (type: `integer`):

Required accumulated review count for both versions before declaring regression or no regression.

## `regressionThreshold` (type: `number`):

Minimum average-rating drop from the immediately preceding observed version.

## `stateKey` (type: `string`):

Stable lowercase key that isolates review IDs and version aggregates between monitors.

## Actor input object example

```json
{
  "appIds": [],
  "searchTerms": [
    "budget planner"
  ],
  "country": "us",
  "maxApps": 5,
  "searchResultsPerTerm": 5,
  "maxReviewPages": 2,
  "maxReviews": 100,
  "minimumReviewsPerVersion": 5,
  "regressionThreshold": 0.5,
  "stateKey": "default"
}
```

# Actor output Schema

## `reviews` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `failures` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "budget planner"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ambitious_ross_tj2/mobile-app-reviews-scraper-version-radar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "searchTerms": ["budget planner"] }

# Run the Actor and wait for it to finish
run = client.actor("ambitious_ross_tj2/mobile-app-reviews-scraper-version-radar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "budget planner"
  ]
}' |
apify call ambitious_ross_tj2/mobile-app-reviews-scraper-version-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ambitious_ross_tj2/mobile-app-reviews-scraper-version-radar"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/k3rT0XDxC3Sf3viah/builds/Gf3OymRHkx5VocoRq/openapi.json