# Google Play Rankings Scraper (`googleapi/google-play-rankings-scraper`) Actor

Extract explicitly ranked public Google Play apps and optionally enrich them with source-backed app details, install bands, update information, screenshots, and ratings.

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

## Pricing

from $3.99 / 1,000 results

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

### What this Actor does

Google Play Rankings Scraper collects apps with an explicit position on the public **Top free** category chart. Optional enrichment adds details visible on each app's public listing. The Actor supports Top free rankings only and reports the positions shown by Google Play; it does not estimate ranking changes.

### Input

Choose a category and ranking type, or provide public category or app URLs. App package IDs can also be supplied directly. `maxApps` limits ranked apps per category and `maxItems` caps total rows. Set `includeDetails` to `true` to add public app listing details; `maxDetailItems` caps the number of apps enriched.

```json
{"category":"TRAVEL_AND_LOCAL","maxItems":20}
```

```json
{"startUrls":[{"url":"https://play.google.com/store/apps/category/TRAVEL_AND_LOCAL?hl=en&gl=US"}],"includeDetails":true,"maxDetailItems":5}
```

```json
{"appIds":["com.example.travel","com.example.maps"],"locale":"en-US","maxItems":10}
```

| Input | Description | Default |
|---|---|---:|
| `category` | Google Play category slug, such as `TRAVEL_AND_LOCAL`. | `TRAVEL_AND_LOCAL` |
| `rankingType` | Ranking shelf to collect. The current option is `top_free`. | `top_free` |
| `startUrls` | Public category or app listing URLs. `sourceUrls`, `urls`, and `url` are aliases. | — |
| `appId` / `appIds` | One or more package IDs for direct app detail records. | — |
| `maxApps` | Maximum ranked apps per category (1–500). | 20 |
| `maxItems` | Maximum dataset rows (1–500). | 20 |
| `includeDetails` | Add public details from app listing pages. | `false` |
| `maxDetailItems` | Maximum ranked apps to enrich when details are enabled (0–50). | 10 |
| `deduplicate` | Avoid duplicate app records. | `true` |
| `locale` / `language` / `country` | Select the Google Play storefront and language. | — |
| `proxyConfiguration` | Optional Apify Proxy configuration for public listing pages. | — |

Only the first public ranking page is supported; `page` and `maxPages` are fixed at `1`.

### Dataset output

Each row describes an app and its visible chart position. Useful fields include `appId`, `title`, `appUrl`, `developer`, `rank`, `rankType`, `rankBadge`, `categorySlug`, `shelf`, `rating`, `reviewCountText`, `ratingBreakdown`, `installsText`, `installsLowerBound`, `installsIsLowerBound`, `description`, `descriptionHtml`, `whatsNew`, `version`, `updatedAt`, `releaseDate`, `minimumAndroidVersion`, `contentRating`, `price`, `dataSafety`, `appIconUrl`, `screenshotUrls`, `locale`, and `country`.

```json
{
  "appId": "com.example.travel",
  "title": "Example Travel",
  "rank": 1,
  "rankType": "top_free",
  "categorySlug": "TRAVEL_AND_LOCAL",
  "rating": 4.6,
  "reviewCountText": "453K reviews",
  "installsText": "10M+",
  "installsLowerBound": 10000000,
  "installsIsLowerBound": true,
  "country": "US"
}
```

Google Play may display rounded review totals and install bands. The Actor preserves the displayed text and marks estimates or lower bounds instead of presenting them as exact counts. Detail fields appear when they are visible on the listing. Download dataset results as JSON, CSV, Excel, or another format supported by Apify.

### Cost and responsible use

Check the Actor's Pricing tab for current Actor and platform charges. Enabling app detail enrichment adds public page requests. Results reflect the selected market and the listing at run time; availability and displayed values may change. Follow Google Play's terms and applicable laws.

# Actor input Schema

## `category` (type: `string`):

Google Play category slug used when no custom URL or app ID is supplied, for example TRAVEL_AND_LOCAL.

## `rankingType` (type: `string`):

Read the displayed Top free ranks from the ordinarily rendered public category chart.

## `startUrls` (type: `array`):

Optional HTTPS play.google.com category or app details URLs. When supplied, these URLs replace the generated category URL.

## `sourceUrls` (type: `array`):

Compatibility alias for startUrls. Accepts HTTPS Google Play URL strings.

## `urls` (type: `array`):

Compatibility alias for startUrls. Accepts HTTPS Google Play URL strings.

## `url` (type: `string`):

Compatibility alias for one category or app details URL.

## `appId` (type: `string`):

Read one public app details page by its package ID, for example com.example.travel.

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

Read up to 50 public app details pages by package ID.

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

Maximum ranked app rows to consider from each category page.

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

Global maximum across category URLs and app IDs.

## `page` (type: `integer`):

Only the first rendered public ranking page is supported.

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

One rendered public ranking page per source is supported.

## `deduplicate` (type: `boolean`):

Deduplicate repeated package IDs across every supplied source.

## `includeDetails` (type: `boolean`):

Fetch public app pages for enrichment. Disabled by default to limit external requests.

## `maxDetailItems` (type: `integer`):

Maximum ranked apps to enrich from public detail pages when includeDetails is enabled; 0 disables detail requests.

## `locale` (type: `string`):

Language-country locale, such as en-US. Explicit locale values must agree with language and country inputs.

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

Two-letter Google Play language code.

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

Two-letter Google Play country code.

## `location` (type: `string`):

Compatibility alias for country.

## `requestTimeoutSecs` (type: `integer`):

Maximum time for each public page request.

## `requestDelayMs` (type: `integer`):

Wait this long between public page requests. Challenges and rate limits stop the run without retrying around them.

## `maxRequestRetries` (type: `integer`):

Bounded retries for network timeouts and server errors. HTTP 401, 403, 429, and verification pages are not retried.

## `maxResponseBytes` (type: `integer`):

Maximum bytes read from one page response.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy configuration. The Actor does not solve CAPTCHAs or bypass Google Play access controls.

## Actor input object example

```json
{
  "category": "TRAVEL_AND_LOCAL",
  "rankingType": "top_free",
  "maxApps": 20,
  "maxItems": 20,
  "page": 1,
  "maxPages": 1,
  "deduplicate": true,
  "includeDetails": false,
  "maxDetailItems": 10,
  "requestTimeoutSecs": 30,
  "requestDelayMs": 1000,
  "maxRequestRetries": 1,
  "maxResponseBytes": 2500000
}
```

# Actor output Schema

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

No description

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

No description

## `runHealth` (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("googleapi/google-play-rankings-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("googleapi/google-play-rankings-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 '{}' |
apify call googleapi/google-play-rankings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-play-rankings-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/SU5l4jYPQaKULdsDJ/builds/LPzafIE9oeBHhBOsn/openapi.json