# Apple App Store Reviews Scraper & Rating Intelligence (`azzarilabs/apple-app-store-reviews-intelligence`) Actor

Extract public Apple App Store reviews by storefront and calculate deterministic rating intelligence.

- **URL**: https://apify.com/azzarilabs/apple-app-store-reviews-intelligence.md
- **Developed by:** [Azzari Labs](https://apify.com/azzarilabs) (community)
- **Stats:** 2 total users, 1 monthly users, 90.9% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 review results

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

## Apple App Store Reviews Scraper & Rating Intelligence

A single public Apify Actor for collecting public Apple App Store reviews by country storefront. It uses Apple iTunes Lookup for app metadata and Apple's public customer-review JSON feed for review records. Acquisition is HTTP-only: no browser, login, cookies, configured proxy, paid API, AI service, or residential proxy.

### Input

Provide `app_id` or an `apps.apple.com` `app_url`. The Python contract requires at least one and rejects conflicting IDs. `countries` defaults to `["US"]` and accepts at most 10 unique two-letter storefront codes. `max_reviews` defaults to 100 and is capped at Apple's observed maximum of 500 recent reviews per app/country. `include_rating_intelligence` defaults to true. The Input Schema intentionally leaves `app_id` and `app_url` optional because Apify Input Schema does not support using `anyOf` to express this rule.

```json
{
  "app_id": "310633997",
  "countries": ["US", "GB"],
  "max_reviews": 100,
  "include_rating_intelligence": true
}
```

### Output

Every valid review is written as one Dataset item with app metadata, country, stable `review_id`, title, text, 1–5 rating, review version/date/author, helpful vote count and sum when Apple exposes them, storefront rating metadata, and warnings. Missing optional evidence remains `null`; the Actor does not invent developer replies or other fields.

`OUTPUT` summarizes app metadata, requested/completed countries, reviews delivered, pages fetched, deterministic rating intelligence, warnings, Dataset ID, and the report reference. `REPORT.html` provides a responsive summary, star distribution, rating shares, country comparison, review table, warnings, and methodology. Empty feeds and nonexistent apps produce valid empty outputs.

### Deterministic rating intelligence

The Actor calculates delivered-review average, 1–5 star distribution, counts and shares for negative (1–2), neutral (3), and positive (4–5) reviews, plus reviews by version. Lowest-rated version and highest/lowest country are returned only when each compared group has at least three delivered reviews; otherwise those values are `null` with an explicit insufficient-sample warning. No AI sentiment, topic inference, or unsupported benchmark is performed.

### Pagination and reliability

Apple's public feed was observed to return 50 reviews per page for pages 1–10; page 11 returns HTTP 400. The Actor never requests beyond 10 pages or 500 reviews per country. Countries are isolated, at most four storefront requests run concurrently, every request has a 10-second timeout, and only transient failures (`429`, `500`, `502`, `503`, `504`, connection errors, and timeouts) receive two moderate retries. Deduplication uses `country + review_id`, never review text.

The feed is a legacy public surface without an SLA. Storefront data, current versions, ratings, counts, and review availability can differ by country. Helpful vote fields may be zero or absent.

### Billing and free use

The prepared PPE event is `review-result`. One event is charged only after a valid review is written to the Dataset. Metadata, empty feeds, invalid apps, failures, discarded rows, duplicates, OUTPUT, and REPORT are not billable. The price remains unset until Cloud cost validation. The evergreen sample requires no secrets and fetches at most 100 reviews from one storefront, keeping ADWIC comfortably below five minutes under the validated acquisition profile.

# Actor input Schema

## `app_id` (type: `string`):

Numeric Apple App Store application ID. Required when App URL is empty.

## `app_url` (type: `string`):

Optional apps.apple.com application URL containing the numeric app ID.

## `countries` (type: `array`):

Two-letter Apple storefront country codes, for example US, GB, or ES. Up to 10 unique countries.

## `max_reviews` (type: `integer`):

Maximum recent reviews to deliver from each storefront, from 1 through Apple's observed limit of 500.

## `include_rating_intelligence` (type: `boolean`):

Calculate deterministic star distribution, rating shares, version aggregates, and country comparisons.

## Actor input object example

```json
{
  "countries": [
    "US"
  ],
  "max_reviews": 100,
  "include_rating_intelligence": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `output` (type: `string`):

No description

## `report` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("azzarilabs/apple-app-store-reviews-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("azzarilabs/apple-app-store-reviews-intelligence").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 '{}' |
apify call azzarilabs/apple-app-store-reviews-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,azzarilabs/apple-app-store-reviews-intelligence"
        }
    }
}
```

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/2NL65yLAcgPtryjyB/builds/bTByneRzZLXY39sFH/openapi.json