# Google Play Reviews API: Reviews by Package and Language (`ailu_studio/google-play-reviews`) Actor

Fetch Google Play app reviews by package name or Play Store URL, language and country: score, text, thumbs up, app version, date, developer reply, plus app rating summary. No browser, no login, no proxies.

- **URL**: https://apify.com/ailu_studio/google-play-reviews.md
- **Developed by:** [Ailu Studio](https://apify.com/ailu_studio) (community)
- **Categories:** E-commerce, Marketing, Agents
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 reviews

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Play Reviews API: App Reviews by Package Name and Language

Fetch Google Play user reviews for any Android app and get them as clean, flat rows: star score, review text, thumbs-up count, app version, date, and the developer's reply when there is one, together with the app title and a direct review URL. Give the Actor one or more package names or Play Store URLs, a language and a country, pick the sort order (newest, rating or helpfulness) and how many reviews to read per app, optionally filter by score, and it reads the public Play Store pages through the open-source `google-play-scraper` library. One free summary row per app adds the current average score, rating and review counts, installs, version, last update and price. No browser, no login, no proxies, so it runs in seconds and works well as an MCP tool for AI agents and in scheduled automations.

### Use cases

- Product and support teams: pull the newest 1- and 2-star reviews of your Android app every morning and route them to Slack or a ticket queue.
- Competitive analysis: compare scores, complaints and developer responsiveness for several competing apps in different countries and languages.
- Sentiment and topic analysis: build a dataset of recent reviews per app version to see which release introduced a problem.
- AI agents: answer "what are Android users saying about app X this week?" with one structured call.
- Localisation research: fetch reviews in `de`, `ja` or `pt-BR` to see how an app is received in a specific market.

### Input

| Field | Default | Meaning |
|---|---|---|
| `apps` | `["com.spotify.music"]` | Android package names or Play Store URLs containing `?id=<package>`. |
| `lang` | `en` | Language code (`hl`), e.g. `en`, `de`, `pt-BR`. |
| `country` | `us` | Two-letter Play Store country (`gl`), e.g. `us`, `gb`, `in`. |
| `sortBy` | `newest` | `newest`, `rating` or `helpfulness`; decides which reviews come first when the run is capped. |
| `maxReviewsPerApp` | `100` | Reviews to read per app, 1 to 2000 (150 per request). |
| `minRating` | – | Keep only reviews with this score or higher (1 to 5). |
| `maxRating` | – | Keep only reviews with this score or lower (1 to 5). |
| `includeAppMetadata` | `true` | Add one free `rowType: "app"` summary row per app. |
| `maxItems` | `500` | Maximum charged review rows per run. |

The default run returns the 100 newest English reviews of Spotify (`com.spotify.music`) from the US store plus one app row.

### Output

| Field | Meaning |
|---|---|
| `id` | Stable key: `<appId>:<reviewId>`, or `<appId>:app` for the summary row. |
| `rowType` | `review` (charged) or `app` (free summary row). |
| `appId`, `appName` | Package name and app title. |
| `reviewId`, `userName`, `text` | Google's review id, reviewer display name, review text (paragraph breaks preserved). |
| `score` | Stars 1 to 5 as a number. |
| `thumbsUp` | How many users marked the review as helpful. |
| `version` | App version the review was written for (may be `null`). |
| `date` | ISO 8601 UTC time the review was written or last edited. |
| `replyText`, `replyDate` | Developer's public reply and its time, or `null`. |
| `url` | Play Store URL of the review (`...&reviewId=<id>`). |
| `lang`, `country` | Language and store country the row was fetched with. |
| `fetchedAt` | ISO 8601 UTC fetch time. |

App rows (`rowType: "app"`) additionally carry `developer`, `developerId`, `genre`, `score` (average), `ratingCount`, `reviewCount`, `installs`, `minInstalls`, `updatedAt`, `releasedAt`, `free`, `price`, `currency` and `contentRating`.

```json
{
  "id": "com.spotify.music:0dd86112-a978-4d4f-a7f3-79d1552ba045", "rowType": "review",
  "appId": "com.spotify.music", "appName": "Spotify: Music and Podcasts",
  "reviewId": "0dd86112-a978-4d4f-a7f3-79d1552ba045", "userName": "Sonia Lafontaine",
  "text": "The best", "score": 5, "thumbsUp": 0, "version": "9.0.60.614",
  "date": "2026-11-02T15:04:06.172Z", "replyText": null, "replyDate": null,
  "url": "https://play.google.com/store/apps/details?id=com.spotify.music&reviewId=0dd86112-a978-4d4f-a7f3-79d1552ba045",
  "lang": "en", "country": "us", "fetchedAt": "2026-11-03T15:00:00.000Z"
}
```

The run summary (apps processed, requests made, reviews seen, errors) is stored in the `OUTPUT` record of the default key-value store.

### How it works and limits

- For each app the Actor loads the app details page once (title, URL and the free summary row) and then requests reviews from the Play Store's internal `batchexecute` endpoint in pages of 150, following the continuation token until `maxReviewsPerApp`, `maxItems` or the last page is reached. It uses the open-source `google-play-scraper` library, not a browser.
- This is unofficial access to public Play Store pages. Google does not document or guarantee the endpoint; if the page format changes, the run may return no reviews until the library is updated.
- Google may rate-limit or temporarily block clients that request too much. The Actor sends at most one request per second and retries transient errors (429, 5xx, network) three times with exponential back-off. Keep volumes modest: a few hundred reviews per app per run is safe; thousands of reviews across many apps may be throttled.
- Rating filters are applied after fetching, so a page is always read in full; filtered-out reviews are not charged.
- Reviews are returned in the requested language and store only; Google decides which reviews appear in a given `lang`/`country` combination. `version` is `null` when Google does not show it.
- An app that does not exist (404) is reported in the run summary and the run finishes with status `partial`.

### Pricing

Pay per result: **$0.50 per 1,000 rows** (`result` event). Platform usage is billed separately by Apify. Removed/free rows are not charged.

A default run (one app, 100 reviews) takes a few seconds and two requests.

### Legal

Not affiliated with Google LLC. Uses the public Google Play Store web pages only (through the open-source google-play-scraper library). Data licence/terms: https://play.google.com/intl/en_us/about/play-terms/ (reviews are user-generated content published by Google; use them in accordance with Google's terms and applicable law).

### FAQ

**Where do I find the package name?** It is the `id` parameter in any Play Store URL, e.g. `https://play.google.com/store/apps/details?id=com.spotify.music` gives `com.spotify.music`. You can paste the whole URL into `apps`.

**Can I get all reviews of an app?** Up to 2,000 per app per run. For a complete history, run the Actor regularly with `sortBy: "newest"` and deduplicate on `id`.

**How do I get only negative reviews?** Set `minRating: 1` and `maxRating: 2`. Pages are still read in full, but only matching reviews are returned and charged.

**Why do I get fewer reviews than requested?** Google shows a limited number of reviews per language and country, and stops paging when they run out. Try another `lang` or `country`, or a different `sortBy`.

**What happens if Google blocks the request?** The Actor retries with back-off; if it still fails, the app is listed in `errors` in the run summary and the run finishes with status `partial` or `failed`. Wait a while and run again with a smaller `maxReviewsPerApp`.

# Actor input Schema

## `apps` (type: `array`):

One or more apps as Android package names (e.g. "com.spotify.music") or Play Store URLs containing ?id=<package> (e.g. "https://play.google.com/store/apps/details?id=com.spotify.music").

## `lang` (type: `string`):

Language code of the reviews and app details to fetch (Play Store "hl" parameter), e.g. "en", "de", "pt-BR". Default "en".

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

Two-letter country code of the Play Store to use ("gl" parameter), e.g. "us", "gb", "in". Default "us".

## `sortBy` (type: `string`):

Order Google applies before paging: newest reviews first, highest ratings first, or most helpful first. It decides which reviews are included when maxReviewsPerApp or maxItems cuts the run short.

## `maxReviewsPerApp` (type: `integer`):

How many reviews to read per app, 1 to 2000 (default 100). Reviews are fetched 150 per request, so 2000 reviews need about 14 requests spaced one second apart. Rating filters are applied after reading.

## `minRating` (type: `integer`):

Keep only reviews with this score or higher (1 to 5). Optional; filtering happens after fetching, so it does not reduce the number of requests.

## `maxRating` (type: `integer`):

Keep only reviews with this score or lower (1 to 5). Set minRating=1 and maxRating=2 to collect only negative reviews. Optional.

## `includeAppMetadata` (type: `boolean`):

When true (default), one extra row with rowType "app" per app is added: title, developer, genre, average score, rating and review counts, installs, version, last update, price. These rows are free (not charged).

## `maxItems` (type: `integer`):

Upper limit on charged review rows for this run (default 500). Free app-summary rows do not count.

## Actor input object example

```json
{
  "apps": [
    "com.spotify.music"
  ],
  "lang": "en",
  "country": "us",
  "sortBy": "newest",
  "maxReviewsPerApp": 100,
  "includeAppMetadata": true,
  "maxItems": 500
}
```

# Actor output Schema

## `results` (type: `string`):

All rows in the default dataset.

# 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 = {
    "apps": [
        "com.spotify.music"
    ],
    "lang": "en",
    "country": "us"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ailu_studio/google-play-reviews").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 = {
    "apps": ["com.spotify.music"],
    "lang": "en",
    "country": "us",
}

# Run the Actor and wait for it to finish
run = client.actor("ailu_studio/google-play-reviews").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 '{
  "apps": [
    "com.spotify.music"
  ],
  "lang": "en",
  "country": "us"
}' |
apify call ailu_studio/google-play-reviews --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ailu_studio/google-play-reviews"
        }
    }
}
```

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/t1KE6OiETTnyMuYa1/builds/ED4JUhH75JUJbtY3g/openapi.json