# Google Play Store API (`gauravlabs/google-play-store-api`) Actor

Search Android apps, retrieve app details, and collect Play Store reviews.

- **URL**: https://apify.com/gauravlabs/google-play-store-api.md
- **Developed by:** [Gaurav Kumar Choudhary](https://apify.com/gauravlabs) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 successful play store requests

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?

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 Store API — Python Apify Actor

Search Android apps, explore categories and charts, retrieve app details, and export paginated reviews. Choose country and language, set page and result limits, and download JSON, CSV or Excel from the Apify dataset. Authentication is internal and never appears in client input, output, or client-facing error messages.

### Search apps

```json
{
  "mode": "search",
  "query": "weather",
  "gl": "us",
  "hl": "en",
  "num": 20,
  "maxPages": 2,
  "maxItems": 30,
  "outputMode": "items"
}
```

You may search by `query`, `appsCategory`, or `chart`. Charts support `topselling_free`, `topselling_paid`, and `topgrossing`. `storeDevice` filters devices; `age` applies only to the `FAMILY` category. `num` accepts 1–100, but the source may return fewer results. The `MEDICAL` category is currently unavailable; use a keyword query instead.

### App product details

```json
{
  "mode": "product",
  "productId": "com.discord",
  "gl": "us",
  "hl": "en"
}
```

### Reviews

```json
{
  "mode": "reviews",
  "productId": "com.discord",
  "gl": "us",
  "hl": "en"
}
```

### Pagination and output

Set `maxPages` (default 1, maximum 100) and `maxItems` (default 100, maximum 10,000). Details use one request. Each fetched search or review page uses one request. Reviews return up to 20 records per page and currently support relevance sorting only. Keyword search typically exposes approximately 30 apps in total; this is not an exhaustive store crawl.

Use the returned `next_page_token` as `nextPageToken` to resume manually. Automatic pagination stops at repeated tokens, removes duplicate records, and preserves collected results with a warning if a later request fails.

`outputMode: "items"` exports one app or review per dataset row. The default `summary` exports a single object containing items, pagination, warnings, and request counts. Both modes save the full summary under `OUTPUT` in the key-value store.

App details include available description, download range, screenshots, release notes and developer information. Reviews include normalized `reviewId`, `reviewer`, `text`, `reviewedAt`, `helpfulVotes`, `appVersion`, and developer reply fields, alongside original fields. Missing values remain absent or null; device-dependent version and Android requirements may not be available. `productId` accepts a package ID or Google Play app-details URL.

### Billing and trial limits

Billing is per successfully fetched page or app-details request, not per exported row. There is no Actor start fee. Valid empty responses count as successful requests; failed requests do not incur the request event charge. Apify platform costs may still apply. Set the maximum run charge and page limits before running.

The additional 100-request lifetime Free-plan restriction is currently disabled. Successful requests are billed against available Apify credits on every plan. The owner can enable the per-account lifetime restriction after configuring its private quota ledger; it is not active in this release.

### API access

Use the Actor's API tab in Apify Console to obtain an authenticated example. For synchronous dataset output, call `POST /v2/acts/gauravlabs~google-play-store-api/run-sync-get-dataset-items` with your Apify API token and one of the input objects above. For larger jobs, start an asynchronous run and retrieve the dataset after completion.

# Actor input Schema

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

Search apps, retrieve app details, or collect reviews.

## `query` (type: `string`):

Keyword search phrase, for example weather, fitness tracker or medical.

## `appsCategory` (type: `string`):

Optional category identifier, for example GAME_PUZZLE, FAMILY or COMMUNICATION. MEDICAL browsing is unavailable; use query medical instead.

## `chart` (type: `string`):

Optional chart: topselling_free, topselling_paid, or topgrossing.

## `productId` (type: `string`):

Required for product and reviews mode, for example com.discord, com.whatsapp, or https://play.google.com/store/apps/details?id=com.discord.

## `hl` (type: `string`):

Language code for returned content, e.g. en.

## `gl` (type: `string`):

Country code used for local results, e.g. us.

## `num` (type: `integer`):

Requested search page size (1-100). Google usually exposes around 30 keyword results total. Review pages contain 20 items.

## `maxPages` (type: `integer`):

Maximum successful page requests for search or reviews. Each page is a separate billing event.

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

Maximum unique apps or reviews to return. Limits output, not the size or cost of already-requested pages.

## `outputMode` (type: `string`):

Summary preserves response compatibility; items writes one app or review per row for CSV and Excel.

## `nextPageToken` (type: `string`):

Optional pagination token from a previous search or review result.

## `storeDevice` (type: `string`):

Optional device: phone, tablet, tv, chromebook, watch, or car.

## `age` (type: `string`):

For FAMILY category only: AGE_RANGE1, AGE_RANGE2, or AGE_RANGE3.

## Actor input object example

```json
{
  "mode": "search",
  "query": "weather",
  "hl": "en",
  "gl": "us",
  "num": 20,
  "maxPages": 1,
  "maxItems": 100,
  "outputMode": "summary"
}
```

# Actor output Schema

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

Full response or one app/review per row, according to outputMode.

## `response` (type: `string`):

All results, pagination, request counters, warnings and safe errors.

# 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 = {
    "query": "weather"
};

// Run the Actor and wait for it to finish
const run = await client.actor("gauravlabs/google-play-store-api").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 = { "query": "weather" }

# Run the Actor and wait for it to finish
run = client.actor("gauravlabs/google-play-store-api").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 '{
  "query": "weather"
}' |
apify call gauravlabs/google-play-store-api --silent --output-dataset

```

## MCP server setup

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

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/D0D0cH2GUDJpyEfR7/builds/Nb5Az85c1Vr3Z950j/openapi.json