---
name: apify-play-store-rankings
description: Track Play Store rankings for the keywords that matter with the Apify Google Play API Actor (johnvc/google-play-api). Each run returns the ranked app list for a keyword with position, title, developer, rating, downloads band and package name, per storefront country and language, so successive runs turn into an ASO rank history for your app and every competitor. Spot position drops after listing changes, watch a competitor climb, or prove ASO wins to a client with data you own. Use when the user wants play store rankings, app store position tracking on Android, ASO keyword rank checks, or google play search positions as JSON. Pay per result, MCP-ready for Claude and other AI agents.
author: John Cole
author_url: https://github.com/johnisanerd
license: MIT
metadata:
  version: "1.0"
---

# Play Store Rankings Tracker for App Keywords (ASO)

An ASO rank tracker for Google Play: keyword in, the ranked app list out, with your app's position per storefront per run accumulating into a history.

## When to use this skill

- The user wants "play store rankings" or Android keyword position tracking.
- An ASO team wants rank history per keyword per storefront for their app and competitors.
- They shipped listing changes and want to see position movement afterward.
- They want a daily or weekly scheduled rank pull as JSON.

Not for: listing metadata or reviews (use the companion apify-google-play-scraper skill), category top charts (search rankings only), or iOS rankings (Apple App Store Search, see `references/actor-index.md`).

## What you get

The ranking signal, one row per app per keyword run:

- `position` is the rank for that keyword at run time; rows arrive in ranked order
- `productId` (package name) is the stable key to find your app and competitors across runs
- `title`, `developer`, `rating`, `downloads` band for the competitive context around each rank
- `query` echo plus your run timestamp make each row self-describing in history

## Prerequisites

- Apify account (sign up at https://apify.com?fpr=9n7kx3&fp_sid=skillrepo).
- Authentication via `apify login`, or an `APIFY_TOKEN` environment variable (Apify Console, Settings, Integrations).

## The Actor

- Store page: https://apify.com/johnvc/google-play-api?fpr=9n7kx3&fp_sid=skillrepo
- Actor ID: `johnvc/google-play-api`
- Pricing: pay per event; see the cost section below and `references/gotchas.md` for live-price commands.

## Run it with the Apify CLI

Rank check one keyword (top 50, US storefront):

```bash
apify actors call "johnvc/google-play-api" -i '{"search_mode":"search","query":"meditation app","max_results":50}' \
  --json \
  --user-agent apify-awesome-skills/apify-play-store-rankings \
  2>/dev/null
```

Same keyword, German storefront:

```bash
apify actors call "johnvc/google-play-api" -i '{"search_mode":"search","query":"meditation app","max_results":50,"country":"de","language":"de"}' \
  --json \
  --user-agent apify-awesome-skills/apify-play-store-rankings \
  2>/dev/null
```

Confirm live pricing and the input schema before a large batch:

```bash
apify actors info "johnvc/google-play-api" --json \
  --user-agent apify-awesome-skills/apify-play-store-rankings \
  2>/dev/null
```

Every call carries the three flags this repo expects: `--json`, `--user-agent apify-awesome-skills/apify-play-store-rankings`, and `2>/dev/null`.

## Run it from Claude or another AI agent (MCP)

The Actor is MCP-ready. Add the hosted server URL:

`https://mcp.apify.com/?tools=actors,docs,johnvc/google-play-api`

Then ask, for example: "Search Google Play for "meditation app" and tell me what position com.calm.android holds and who ranks above it." MCP setup docs: https://docs.apify.com/platform/integrations/mcp

## Workflow

1. Fix the keyword list and storefronts (`country` plus `language`); comparability requires identical inputs per run.
2. Run one search per keyword per storefront on a schedule; `max_results` 50 covers realistic rank movement.
3. Find your app by `productId` per run; record `position` (absent means below the cutoff).
4. Track named competitors the same way in the same rows at no extra cost.
5. Alert on drops beyond a threshold and diff the apps ranked above you for new entrants.

## Inputs

- `search_mode` (enum `search`, `product`, `reviews`, required, default `search`)
- `query` (string): keyword for search mode, for example "meditation"
- `product_id` (string): the app package name for `product` and `reviews` modes, for example `com.spotify.music`
- `max_results` (integer, default 100): the cost driver in search and reviews modes
- `country` (string, default `us`): storefront country
- `language` (string, default `en`): storefront language

## Cost

Billing is pay per event, plus a negligible platform fee per dataset row. Prices below are the BRONZE tier at the time of writing; confirm live prices with the info command above.

- About $0.00075 per app row. A 50-row keyword check is about $0.04.
- 20 keywords daily at 50 rows each is about $0.75 per day.

Suggested confirmation thresholds: warn the user over about $5; get explicit confirmation over about $20. Present cost as "around $X", never a guarantee.

## Honest limits

- Search rankings are storefront-specific and personalize less than web search, but still move; same-day reruns can differ slightly.
- Rows below `max_results` are invisible; a missing app is "below cutoff", not "gone".
- Category top charts are not exposed here; this tracks keyword search rankings.

## Troubleshooting

- Your app never appears: confirm the package name and that it is live in that `country` storefront.
- Ranks jump around: verify the schedule keeps `country` and `language` fixed; mixed storefronts do not compare.
- One `errorMessage` row: clean upstream failure; skip the datapoint rather than recording it as a drop.

See `references/gotchas.md` for cost guardrails and error recovery, and `references/actor-index.md` for the Actor routing table.

## Related Actors

- Apple App Store Reviews API: https://apify.com/johnvc/apple-app-store-reviews-api?fpr=9n7kx3&fp_sid=skillrepo
- Apple App Store Search: https://apify.com/johnvc/apple-app-store-search?fpr=9n7kx3&fp_sid=skillrepo
- Apple App Store Product API: https://apify.com/johnvc/apple-app-store-product-api?fpr=9n7kx3&fp_sid=skillrepo