# Google Play Store Scraper (`karamelo/google-play-store-scraper`) Actor

Scrape Google Play Store apps, search rankings, reviews, and category top charts. Extract ratings, installs, pricing, developer contacts, and full metadata without API keys.

- **URL**: https://apify.com/karamelo/google-play-store-scraper.md
- **Developed by:** [karamelo](https://apify.com/karamelo) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.10 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

### 🚀 What does Google Play Store Scraper do?

Google Play Store Scraper is a high-performance web extraction tool designed to collect comprehensive Android application intelligence, user review sentiment, search rankings, and category charts directly from Google Play. Whether you are conducting app store optimization (ASO) research, auditing market competitors, analyzing consumer feedback, or feeding mobile software datasets into machine learning pipelines, this Actor extracts structured, clean, and normalized data without requiring private credentials, mobile emulators, or complex developer accounts.

The Actor operates across four dedicated operating modes within a single unified interface:

- 🔍 **Search Mode (`search`)** — Query Google Play using targeted keyword phrases (for example, "podcast player", "habit tracker", "budget planner") to uncover ranking applications, keyword positioning, top developers, and key listing metrics.
- 🏆 **Top Charts Mode (`topCharts`)** — Discover ranked listings across Top Free, Top Paid, and Top Grossing collections for any standard category (including Business, Productivity, Finance, Education, Entertainment, and Games) with verified rank positions.
- 📱 **App Details Mode (`details`)** — Extract the complete 47+ field profile for specific package identifiers or URLs (such as `org.videolan.vlc`, `com.duolingo`, or `com.notion.id`), covering developer contact info, install volume estimates, version changelogs, full descriptions, in-app purchase offerings, and ratings breakdowns.
- 💬 **Reviews Mode (`reviews`)** — Collect authentic customer reviews, star scores, review titles, user feedback commentary, developer responses, helpfulness vote counts, and historical submission dates across specific apps with granular rating filters and sorting options.

All extracted data is delivered in flat, schema-compliant JSON, CSV, and Excel tables ready for immediate analysis in Google Sheets, business intelligence dashboards, or database warehouses.

***

### ✨ Why use Google Play Store Scraper?

- 🔑 **Zero API Keys or Platform Credentials Required** — Run immediately without registering developer consoles, managing private tokens, or facing restricted developer account quotas.
- 🎛️ **Four Integrated Modes in One Automation** — Eliminate the friction of configuring separate tools for keyword discovery, rank tracking, metadata enrichment, and customer sentiment mining.
- 📦 **Exhaustive 47+ Field Metadata Extraction** — Capture deep metadata beyond superficial listings, including developer corporate address, registered legal entity, direct support email, in-app purchase flags, star rating histograms, interactive screenshot links, and update changelogs.
- 🎯 **Flexible Review Sorting and Filtering** — Target critical user feedback by isolating specific 1-star pain points or 5-star praise, with customizable sorting by newest submissions, user ratings, or algorithmic relevance.
- 🌍 **Native Localization and Regional Availability** — Scrape storefronts across any country and language combination (for instance, United States, Germany, Japan, Brazil, United Kingdom, France) to analyze localized app titles and country-specific review patterns.
- ⚡ **Optimized Proxy Architecture** — High-speed Datacenter proxies are enabled by default for maximum throughput, efficiency, and minimal resource usage.
- 📊 **Flat, Database-Ready Output Architecture** — Every record is pre-formatted as flat rows with zero deep nesting, ensuring seamless exports into Google Sheets, PostgreSQL, Airtable, Snowflake, and BigQuery.
- 🔄 **Integrated Apify Ecosystem Compatibility** — Schedule recurring daily or weekly monitoring jobs, trigger automated webhooks upon job completion, and connect directly to Zapier, Make, or custom API endpoints.

***

### 👥 Who is this Actor for?

#### 💻 Mobile App Developers & Indie Creators

- 🛠️ **Competitor Feature Audits**: Track competitor changelogs and release notes to observe new feature rollouts, bug fixes, and development velocity in real time.
- 🔍 **UX & Usability Gap Analysis**: Filter negative 1-star and 2-star reviews across rival applications to pinpoint recurring software crashes, design friction, and unaddressed consumer demands.
- 📈 **Benchmarking Performance**: Benchmark your install velocity, average rating score, and rating volume against category leaders in your niche.

#### 📈 App Store Optimization (ASO) & Growth Marketers

- 🔎 **Keyword Placement Tracking**: Monitor which applications rank on top positions for competitive search keywords and monitor shifts in rank over time.
- 🎨 **Visual Asset & Copy Research**: Compare promotional icons, feature graphic header images, screenshot compositions, and promotional summaries to refine listing conversions.
- 🌐 **International Market Discovery**: Identify localized metadata and localized user reception in international territories before launching regional expansion campaigns.

#### 🔬 Product Managers & Market Research Analysts

- 🗣️ **Customer Voice Synthesis**: Aggregate thousands of real-world user reviews into language models to generate automated thematic summaries, customer sentiment reports, and feature request backlogs.
- 📊 **Market Saturation Assessment**: Quantify the density of competing applications within emerging sectors such as AI assistants, meditation aids, fitness coaching, and personal budgeting.
- 🏷️ **Feature & Monetization Analysis**: Examine category monetization models across free and paid apps and evaluate common in-app purchase (IAP) patterns across market segments.

#### 💼 Investment Analysts & Due Diligence Teams

- 🚀 **Traction & Engagement Due Diligence**: Validate candidate app install milestones (ranging from 10,000+ to 1,000,000,000+) and review historical update cadences before capital deployment.
- 🏢 **Developer Ecosystem Mapping**: Extract corporate developer emails, website URLs, and verified physical addresses to identify parent organizations and related software portfolios.

***

### 🛠️ Operating Modes in Detail

#### 1. 🔍 Search Mode (`search`)

Search mode enables keyword-based app discovery across the entire Play Store catalog. When given search phrases, the Actor queries the storefront, extracts top ranking applications, and automatically enriches each entry with full app metadata.

- ⚙️ **Primary Inputs**: `searchTerms` (array of strings, e.g., `["podcast player", "habit tracker"]`), `maxResults` (max apps per query), `country`, `language`.
- 📋 **Output Record Highlights**: Every output record contains standard metadata along with the `searchTerm` attribute, allowing you to trace exactly which keyword surfaced each app.

#### 2. 🏆 Top Charts Mode (`topCharts`)

Top Charts mode discovers top trending and ranked mobile applications across standard ranking collections. This is ideal for market monitoring and category intelligence.

- 📊 **Collections Available**:
  - `top-free`: Leading free downloadable applications.
  - `top-paid`: Leading premium purchased applications.
  - `top-grossing`: Applications generating the highest overall store revenue.
- 🏷️ **Category Support**: Supports general applications (`APPLICATION`) as well as specific categories such as `GAME`, `PRODUCTIVITY`, `FINANCE`, `HEALTH_AND_FITNESS`, `EDUCATION`, `COMMUNICATION`, `ENTERTAINMENT`, and `TOOLS`.
- 📋 **Output Record Highlights**: Each record includes `chartRank` (1-indexed numeric ranking), `chartCollection`, and `chartCategory`.

#### 3. 📱 App Details Mode (`details`)

Details mode accepts a list of specific app package identifiers or full Play Store URLs and collects the comprehensive 47+ field profile for each app.

- ⚙️ **Primary Inputs**: `appIds` (array of package names or listing URLs, e.g., `["org.videolan.vlc", "https://play.google.com/store/apps/details?id=com.spotify.music"]`), `country`, `language`.
- 📋 **Output Record Highlights**: Complete technical metrics, developer legal details, ratings histogram, category taxonomies, and content advisories.

#### 4. 💬 Reviews Mode (`reviews`)

Reviews mode gathers individual customer reviews submitted for one or more target applications.

- ⚙️ **Primary Inputs**: `appIds` (target package ID or URL), `maxResults` (maximum reviews to extract), `reviewSort` (`newest`, `rating`, `helpfulness`), `reviewScore` (filter for specific star scores 1 through 5), `country`, `language`.
- 📋 **Output Record Highlights**: Review text, star score, user handle, submission timestamp, developer replies, thumbs-up vote counts, and app version at the time of review.

***

### 📋 Step-by-Step Configuration Guide

1. **Select Operating Mode** 🎯: Choose between `search`, `topCharts`, `details`, or `reviews`.
2. **Specify Target Identifiers or Queries** 📝:
   - For `search` mode: Enter search keyword phrases into **Search terms** (`searchTerms`).
   - For `topCharts` mode: Pick your desired **Chart collection** (`chartCollection`) and **Chart category** (`chartCategory`).
   - For `details` or `reviews` mode: Input package IDs (e.g. `org.videolan.vlc`) or full Google Play URLs into **App IDs or URLs** (`appIds`).
3. **Set Regional Parameters (Optional)** 🌍: Configure **Country code** (`country`) (default: `us`) and **Language code** (`language`) (default: `en`) to target specific geographic storefronts.
4. **Refine Review Filters (Reviews Mode Only)** 💬: Set **Review sort order** (`reviewSort`) and optionally restrict results to a specific rating score via **Filter by star rating** (`reviewScore`) to isolate negative or positive sentiment.
5. **Adjust Limits & Run** 🚀: Set **Maximum results** (`maxResults`) to control dataset size, then click **Start** to execute the Actor.

***

### 💡 Practical Input Examples

#### 🔎 Example 1: Search Discovery Run

Discover top podcast listening applications in the United States storefront:

```json
{
  "mode": "search",
  "searchTerms": [
    "podcast player",
    "audiobook reader"
  ],
  "maxResults": 20,
  "country": "us",
  "language": "en"
}
```

***

#### 🥇 Example 2: Category Top Charts Extraction

Extract the top 25 free productivity applications:

```json
{
  "mode": "topCharts",
  "chartCollection": "top-free",
  "chartCategory": "PRODUCTIVITY",
  "maxResults": 25,
  "country": "us",
  "language": "en"
}
```

***

#### 📦 Example 3: Comprehensive App Details Lookup

Retrieve complete metadata for popular open-source and productivity apps:

```json
{
  "mode": "details",
  "appIds": [
    "org.videolan.vlc",
    "https://play.google.com/store/apps/details?id=com.duckduckgo.mobile.android"
  ],
  "country": "us",
  "language": "en"
}
```

***

#### ⭐ Example 4: Critical Review Extraction (1-Star Only)

Extract recent negative reviews to identify bugs and customer complaints:

```json
{
  "mode": "reviews",
  "appIds": [
    "org.videolan.vlc"
  ],
  "maxResults": 50,
  "reviewSort": "newest",
  "reviewScore": 1,
  "country": "us",
  "language": "en"
}
```

***

### ⚙️ Input Parameters Reference

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `mode` | String | Yes | `"search"` | Scraping mode: `"search"`, `"topCharts"`, `"details"`, or `"reviews"`. |
| `searchTerms` | Array of Strings | No | `[]` | Search phrases used in `search` mode. Example: `["podcast player"]`. |
| `appIds` | Array of Strings | No | `[]` | Package IDs or full URLs used in `details` and `reviews` modes. |
| `chartCollection` | String | No | `"top-free"` | Ranking collection in `topCharts` mode: `"top-free"`, `"top-paid"`, or `"top-grossing"`. |
| `chartCategory` | String | No | `"APPLICATION"` | Category identifier for charts (e.g. `"PRODUCTIVITY"`, `"GAME"`, `"FINANCE"`). |
| `maxResults` | Number | No | `20` | Maximum number of records to return per term, category, or app. |
| `reviewSort` | String | No | `"newest"` | Sorting criteria for reviews: `"newest"`, `"rating"`, or `"helpfulness"`. |
| `reviewScore` | Number | No | `null` | Filter reviews by star score (1 to 5). Leave empty for all ratings. |
| `country` | String | No | `"us"` | Two-letter ISO country code for storefront localization (e.g. `"us"`, `"de"`, `"jp"`). |
| `language` | String | No | `"en"` | Two-letter ISO language code for localized text (e.g. `"en"`, `"es"`, `"fr"`). |

***

### 📊 Complete Output Data Fields

#### 📱 App Records (Search, Top Charts, and Details Modes)

| Category | Field Name | Data Type | Description |
|---|---|---|---|
| **Identity & Overview** | `appId` | String | Unique Android package identifier (e.g. `org.videolan.vlc`). |
| | `title` | String | Official display title of the application. |
| | `summary` | String | Short promotional summary tag line. |
| | `description` | String | Full store listing description text. |
| | `descriptionHTML` | String | HTML formatted store listing description. |
| **Developer Information** | `developer` | String | Public developer display name. |
| | `developerId` | String | Numerical or slug developer identifier. |
| | `developerInternalID` | String | Internal developer store reference ID. |
| | `developerEmail` | String | Public support email address provided by developer. |
| | `developerWebsite` | String | Official developer homepage or company website URL. |
| | `developerAddress` | String | Registered physical corporate address of developer. |
| | `developerLegalName` | String | Registered corporate legal entity name. |
| | `developerLegalEmail` | String | Legal correspondence email address. |
| | `developerLegalAddress` | String | Verified legal mailing address. |
| | `developerLegalPhoneNumber`| String | Registered contact phone number. |
| **Ratings & Feedback** | `score` | Number | Current average customer rating score (1.0 to 5.0). |
| | `scoreText` | String | Formatted text representation of rating score. |
| | `ratings` | Number | Total cumulative count of user ratings submitted. |
| | `reviews` | Number | Total count of written text reviews submitted. |
| | `histogram1star` | Number | Cumulative count of 1-star ratings received. |
| | `histogram2star` | Number | Cumulative count of 2-star ratings received. |
| | `histogram3star` | Number | Cumulative count of 3-star ratings received. |
| | `histogram4star` | Number | Cumulative count of 4-star ratings received. |
| | `histogram5star` | Number | Cumulative count of 5-star ratings received. |
| **Installs & Metrics** | `installs` | String | Human-readable install volume tier (e.g. 500,000,000+). |
| | `minInstalls` | Number | Lower bound of estimated total installs. |
| | `maxInstalls` | Number | Upper bound of estimated total installs. |
| **Pricing & Purchases** | `price` | Number | Purchase price for paid apps (0 for free apps). |
| | `originalPrice` | Number | Pre-discount list price if app is currently discounted. |
| | `discountEndDate` | String | ISO timestamp when current price promotion concludes. |
| | `priceText` | String | Formatted price string (e.g. Free, $3.99). |
| | `free` | Boolean | True if the app is free to download; false if paid. |
| | `currency` | String | Currency code associated with pricing (e.g. USD, EUR). |
| | `offersIAP` | Boolean | Indicates whether app contains in-app purchases. |
| | `inAppProductPrice` | String | Price range of available in-app purchase items. |
| | `androidVersion` | String | Minimum Android OS version required. |
| | `androidVersionText` | String | Display text of OS compatibility (e.g. "4.2 and up"). |
| **Taxonomy & Category** | `genre` | String | Primary category display name (e.g. Video Players & Editors). |
| | `genreId` | String | System category identifier (e.g. VIDEO\_PLAYERS). |
| | `categories` | Array | Array of secondary and related category tags. |
| | `contentRating` | String | Age and content advisory rating (e.g. Everyone, Teen). |
| | `contentRatingDescription` | String | Extended guidance explaining content rating. |
| | `adSupported` | Boolean | True if app displays third-party advertising. |
| | `isAvailableInPlayPass` | Boolean | Indicates inclusion in Google Play Pass subscription. |
| **Version & Release Info**| `version` | String | Latest publicly available software version string. |
| | `released` | String | Initial public launch date of application. |
| | `updated` | Number | Unix timestamp in milliseconds of most recent update. |
| | `recentChanges` | String | Release notes describing recent bug fixes and features. |
| **Media Assets & Links** | `icon` | String | High-resolution square app icon image URL. |
| | `headerImage` | String | High-resolution promotional hero banner image URL. |
| | `screenshots` | Array | Array of high-resolution screenshot image URLs. |
| | `video` | String | Embedded YouTube promotional or gameplay video URL. |
| | `videoImage` | String | Video preview thumbnail cover image URL. |
| | `previewVideo` | String | Preview video asset URL. |
| | `privacyPolicy` | String | Official privacy policy compliance URL. |
| **Workflow Fields** | `url` | String | Direct canonical Play Store listing URL. |
| | `searchTerm` | String | Present in search mode: the originating query term. |
| | `chartRank` | Number | Present in topCharts mode: numeric chart position rank. |
| | `chartCollection` | String | Present in topCharts mode: top-free, top-paid, or top-grossing. |
| | `chartCategory` | String | Present in topCharts mode: active category identifier. |
| | `scrapedAt` | String | ISO 8601 UTC timestamp recording when data was extracted. |

***

#### 💬 Review Records (Reviews Mode)

| Field Name | Data Type | Description |
|---|---|---|
| `reviewId` | String | Unique system identifier for the individual review. |
| `appId` | String | Target package ID the review evaluates. |
| `userName` | String | Public display name of the reviewer. |
| `userImage` | String | Profile avatar image URL of the reviewer. |
| `score` | Number | Numerical star score assigned by reviewer (1 to 5). |
| `scoreText` | String | String representation of star rating. |
| `text` | String | Full text body of the user's review and feedback. |
| `date` | String | ISO 8601 UTC timestamp of review submission. |
| `replyText` | String | Official response text written by the developer, if provided. |
| `replyDate` | String | ISO 8601 UTC timestamp of developer reply, if provided. |
| `thumbsUp` | Number | Count of helpfulness community upvotes. |
| `version` | String | Software version installed by reviewer when writing feedback. |
| `criteriaJson` | String | Structured sub-criteria scores when present. |
| `url` | String | Direct canonical URL for the parent app listing. |
| `scrapedAt` | String | ISO 8601 UTC timestamp of data collection. |

***

### 📄 Sample Output Records

#### 📋 Sample App Detail Record (`details` Mode)

```json
{
  "appId": "org.videolan.vlc",
  "title": "VLC for Android",
  "summary": "VLC for Android is the best open source video and music player, fast and easy!",
  "developer": "Videolabs",
  "developerId": "6364851808230428105",
  "developerEmail": "android-support@videolan.org",
  "developerWebsite": "http://www.videolan.org",
  "developerAddress": null,
  "developerInternalID": "6364851808230428105",
  "developerLegalName": "Videolabs",
  "developerLegalEmail": "android-support@videolan.org",
  "score": 4.04,
  "scoreText": "4.0",
  "ratings": 2003074,
  "reviews": 25661,
  "histogram1star": 273027,
  "histogram2star": 105395,
  "histogram3star": 136871,
  "histogram4star": 236040,
  "histogram5star": 1251686,
  "installs": "500,000,000+",
  "minInstalls": 500000000,
  "maxInstalls": 509719529,
  "price": 0,
  "originalPrice": 0,
  "discountEndDate": null,
  "priceText": "Free",
  "free": true,
  "currency": "USD",
  "offersIAP": false,
  "inAppProductPrice": null,
  "androidVersion": "4.2",
  "androidVersionText": "4.2 and up",
  "developerLegalAddress": null,
  "developerLegalPhoneNumber": null,
  "genre": "Video Players & Editors",
  "genreId": "VIDEO_PLAYERS",
  "categories": [
    { "name": "Video Players & Editors", "id": "VIDEO_PLAYERS" }
  ],
  "icon": "https://play-lh.googleusercontent.com/g_PfqD-pIuD0tqG_hH...",
  "headerImage": "https://play-lh.googleusercontent.com/yFvY_E6f0G1...",
  "screenshots": [
    "https://play-lh.googleusercontent.com/r6b3l1qWv..."
  ],
  "video": null,
  "videoImage": null,
  "previewVideo": null,
  "contentRating": "Everyone",
  "contentRatingDescription": null,
  "adSupported": false,
  "isAvailableInPlayPass": false,
  "released": "May 10, 2012",
  "updated": 1725883012000,
  "version": "3.5.4",
  "recentChanges": "Fix audio player playback notification controls.",
  "privacyPolicy": "http://www.videolan.org/legal.html",
  "url": "https://play.google.com/store/apps/details?id=org.videolan.vlc",
  "scrapedAt": "2026-09-13T15:13:54.340Z"
}
```

***

#### ✍️ Sample User Review Record (`reviews` Mode)

```json
{
  "reviewId": "gp:AOqpTOE4k7fG01h6tX...",
  "appId": "org.videolan.vlc",
  "userName": "Alex Morgan",
  "userImage": "https://play-lh.googleusercontent.com/a/ACg8ocI8...",
  "score": 5,
  "scoreText": "5",
  "text": "Plays every video format without stuttering or audio lag. Best media player available.",
  "date": "2026-09-10T14:22:15.000Z",
  "replyText": null,
  "replyDate": null,
  "thumbsUp": 4,
  "version": "3.5.4",
  "criteriaJson": null,
  "url": "https://play.google.com/store/apps/details?id=org.videolan.vlc",
  "scrapedAt": "2026-09-13T15:13:54.340Z"
}
```

***

### 🔄 Automation & Workflow Integrations

Connect Google Play Store Scraper into your existing cloud infrastructure using native Apify integrations:

- 📊 **Google Sheets & Airtable**: Automatically append newly scraped app reviews or rating changes directly into a shared spreadsheet. Create ongoing historical charts showing how competitor ratings evolve month-over-month.
- 🔔 **Slack & Discord Alerts**: Set up webhook alerts that notify your customer advocacy or product engineering channels whenever new 1-star or 2-star reviews appear for your company app.
- ⚡ **Make & Zapier Automations**: Forward negative reviews into ticketing systems such as Zendesk, Linear, or Jira to instantly escalate critical bugs reported by real mobile users.
- 💾 **BigQuery, Snowflake & S3**: Stream enriched mobile market data into your enterprise analytical warehouse using scheduled weekly batch exports for predictive machine learning models.
- ⏰ **Scheduled Monitoring Runs**: Use Apify's built-in cron scheduler to execute reviews or details runs on recurring cadences (daily, weekly, monthly) without human intervention.

***

### 💻 Programmatic API Usage

Execute this Actor programmatically in your preferred language or development stack.

#### 🟨 Node.js (Official JavaScript SDK)

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

const client = new ApifyClient({
    token: 'YOUR_APIFY_TOKEN',
});

const run = await client.actor('karamelo/google-play-store-scraper').call({
    mode: 'details',
    appIds: ['org.videolan.vlc', 'com.duolingo'],
    country: 'us',
    language: 'en',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Successfully fetched ${items.length} apps:`);
items.forEach((item) => {
    console.log(`- ${item.title}: ${item.score}/5.0 (${item.installs} installs)`);
});
```

#### 🐍 Python (Official Python SDK)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {
    "mode": "reviews",
    "appIds": ["org.videolan.vlc"],
    "maxResults": 30,
    "reviewSort": "newest",
    "reviewScore": 1,
    "country": "us",
    "language": "en",
}

run = client.actor("karamelo/google-play-store-scraper").call(run_input=run_input)

dataset_items = client.dataset(run["defaultDatasetId"]).list_items().items
for review in dataset_items:
    print(f"[{review['score']}*] {review['userName']}: {review['text'][:60]}...")
```

#### 🌐 cURL (REST API)

```bash
curl -X POST "https://api.apify.com/v2/acts/karamelo~google-play-store-scraper/runs" \
     -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "mode": "search",
       "searchTerms": ["podcast player"],
       "maxResults": 10,
       "country": "us"
     }'
```

***

### 🤖 Model Context Protocol (MCP) & AI Agents

Integrate Google Play Store Scraper into autonomous LLM agents and AI development workflows using Apify's hosted Model Context Protocol (MCP) server.

#### 🖥️ Claude Desktop, Cursor, and VS Code Setup

Add this configuration to your local MCP client settings:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=karamelo/google-play-store-scraper"
    }
  }
}
```

#### ⚡ Claude Code CLI Integration

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=karamelo/google-play-store-scraper"
```

#### 🧠 Natural Language Agent Prompts

- 🔍 *"Search Google Play for top meditation apps in the US, compare their ratings, and summarize key features."*
- 🐞 *"Extract the latest 20 1-star reviews for VLC for Android and identify the primary hardware or codec complaints."*
- 📊 *"Audit the top 10 productivity apps in France and compile their average ratings and category rankings."*

***

### ⚠️ Known Limitations & Best Practices

- 🌐 **Public Data Access Scope**: The Actor exclusively scrapes publicly accessible storefront listings visible to unauthenticated web browsers. It does not access private Google Play Developer Console statistics, internal revenue dashboards, or unreleased draft builds.
- 📄 **Search Result Depths**: Google Play's public web search interface typically serves up to approximately 30 to 50 organic results per query keyword. For wider catalog coverage, combine multiple related search phrases or explore specific category top charts.
- 🗺️ **Regional Localization Dependencies**: Storefront availability and review languages vary significantly by geographic territory. Always pair your target `country` and `language` parameters intentionally (for instance, `country: "jp", language: "ja"` for Japanese market results).
- 💬 **Review Volume Availability**: Review volume is contingent on how many public reviews Google has indexed for a given app in the specified locale. Niche apps in smaller regional storefronts may have fewer total reviews available.

***

### 🛡️ Responsible Use & Data Compliance

- ⚖️ **Publicly Available Information**: This Actor collects only publicly visible storefront metadata. It does not bypass paywalls, scrape private user accounts, or defeat authentication systems.
- 🔒 **Privacy & GDPR Considerations**: User review records may contain public user screen names and public reviewer avatars. If you process or export personal data belonging to individuals within the European Economic Area (EEA), ensure your data handling complies with GDPR, California Consumer Privacy Act (CCPA), and relevant regional privacy frameworks.
- 📜 **Terms of Service**: Users are responsible for ensuring that their automated data extraction activities comply with applicable laws, platform terms, and organizational governance guidelines.

***

### ❓ Frequently Asked Questions (FAQ)

**Q: Do I need a Google account or Play Store credentials?** 🔑\
No. The Actor accesses public storefront listings directly. You do not need to provide Google logins, app passwords, or developer API tokens.

**Q: What is an app package ID and how do I find it?** 📱\
The package ID is the unique reverse-domain identifier in an app's Google Play URL. For example, in `https://play.google.com/store/apps/details?id=org.videolan.vlc`, the package ID is `org.videolan.vlc`. You can paste either the full URL or the ID directly into the Actor.

**Q: Can I extract reviews for any app on Google Play?** 💬\
Yes, as long as the app has public reviews available in the specified country and language storefront.

**Q: Why do some fields have null values?** ℹ️\
Certain metadata fields (such as developer physical address, developer phone number, or promotional video) are optional disclosures that not all developers submit to Google Play. If an author omits a detail, that property returns as `null`.

**Q: How do I schedule automatic weekly runs?** ⏰\
Open the Actor in the Apify Console, navigate to the **Schedules** tab, and set your desired cron frequency (e.g. every Monday at 08:00 UTC). New results will automatically appear in your default storage dataset.

**Q: Can I filter reviews to see only negative complaints?** 🎯\
Yes. In `reviews` mode, set `reviewScore: 1` or `reviewScore: 2` to exclusively extract low-star feedback for product and bug research.

# Actor input Schema

## `mode` (type: `string`):

Choose what to scrape: search for apps by keywords 🔍, discover ranked Top Charts 🏆, fetch full details for specific app IDs 📱, or extract user reviews 💬.

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

Keywords to search on Google Play (used in "search" mode). Example: "podcast player", "habit tracker", "budget planner".

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

Google Play app package IDs or URLs (used in "details" and "reviews" modes). Example: "org.videolan.vlc", "com.duolingo".

## `chartCollection` (type: `string`):

Ranking collection to extract in "topCharts" mode.

## `chartCategory` (type: `string`):

Optional Google Play category identifier in "topCharts" mode. Defaults to APPLICATION (all apps). Examples: GAME, PRODUCTIVITY, FINANCE, HEALTH\_AND\_FITNESS, EDUCATION.

## `maxResults` (type: `integer`):

Maximum number of apps or reviews to return per query, chart, or app ID.

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

Two-letter ISO 3166-1 alpha-2 country code for localized pricing and availability (e.g. us, gb, de, fr, jp).

## `language` (type: `string`):

Two-letter ISO 639-1 language code for localized metadata (e.g. en, es, de, fr, ja).

## `reviewSort` (type: `string`):

Sort order for user reviews in "reviews" mode.

## `reviewScore` (type: `integer`):

Only return reviews with this exact star rating (1 to 5). Leave empty for all ratings.

## Actor input object example

```json
{
  "mode": "search",
  "searchTerms": [
    "podcast player",
    "habit tracker"
  ],
  "appIds": [
    "org.videolan.vlc",
    "com.duolingo"
  ],
  "chartCollection": "top-free",
  "chartCategory": "APPLICATION",
  "maxResults": 10,
  "country": "us",
  "language": "en",
  "reviewSort": "newest"
}
```

# Actor output Schema

## `overview` (type: `string`):

Google Play app search and detail records.

## `topCharts` (type: `string`):

Ranked Google Play chart app records with chart context.

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

Google Play user review records.

# 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 = {
    "mode": "search",
    "searchTerms": [
        "podcast player",
        "habit tracker"
    ],
    "appIds": [
        "org.videolan.vlc",
        "com.duolingo"
    ],
    "chartCollection": "top-free",
    "chartCategory": "APPLICATION",
    "maxResults": 10,
    "country": "us",
    "language": "en",
    "reviewSort": "newest"
};

// Run the Actor and wait for it to finish
const run = await client.actor("karamelo/google-play-store-scraper").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 = {
    "mode": "search",
    "searchTerms": [
        "podcast player",
        "habit tracker",
    ],
    "appIds": [
        "org.videolan.vlc",
        "com.duolingo",
    ],
    "chartCollection": "top-free",
    "chartCategory": "APPLICATION",
    "maxResults": 10,
    "country": "us",
    "language": "en",
    "reviewSort": "newest",
}

# Run the Actor and wait for it to finish
run = client.actor("karamelo/google-play-store-scraper").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 '{
  "mode": "search",
  "searchTerms": [
    "podcast player",
    "habit tracker"
  ],
  "appIds": [
    "org.videolan.vlc",
    "com.duolingo"
  ],
  "chartCollection": "top-free",
  "chartCategory": "APPLICATION",
  "maxResults": 10,
  "country": "us",
  "language": "en",
  "reviewSort": "newest"
}' |
apify call karamelo/google-play-store-scraper --silent --output-dataset

```

## MCP server setup

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

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/p5iogxVGKvYGQWrhb/builds/ejeJwr6OfZ5cJx6rm/openapi.json