google-play/
app-rankings

The Google Play App Rankings API collects public Google Play category rankings from known chart URLs as normalized app records with position, identity, store metadata, media, and collection context.

Google Play App Rankings API

Category URL input
Normalized app records
Result-based billing
0.15 credits / result
Ready
Ready

Enter parameters and send a request. The task status and normalized results will appear here.

README

By SocQ · Updated

Google Play App Rankings

A Google Play chart URL identifies the category or ranking surface to collect, while results_limit controls discovery depth from 1 to 2000 records. Each stored result follows the AppItem contract so rank can be analyzed beside available package identity, developer, category, rating, review count, installs, price, media, source URL, and collection time.

Google Play App Rankings API Features

  • Chart URL batchesGive the Google Play App Rankings API a non-empty urls array of public play.google.com category or ranking pages instead of separate country or category fields.
  • Google Play ranking URL validationThe runtime accepts play.google.com and its subdomains only when the path contains /store/apps/collection/ or /store/apps/category/.
  • Bounded ranking collectionUse results_limit from 1 through 2000. Omit it to use 100, which is also the billing estimate and the provider discovery default.
  • Normalized app positionsRead rank with available app_id, name, developer, category, rating, reviews_count, installs, price, media, and public source metadata in one AppItem shape.
  • Asynchronous dataset workflowThe submitted URL rows trigger an asynchronous provider dataset; SocQ stores normalized records and returns task state through the shared task reader.
  • Stored-result cursorAfter success, paginate SocQ records with the task reader's opaque next_cursor and a limit from 1 to 500. This cursor is not a Google Play or provider page token.
  • Actual-result settlementSocQ precharges the requested or default result estimate, then settles at 0.15 credits per stored result and refunds unused estimated credits; an empty result settles to the zero-credit base.

Google Play App Rankings API Parameters

ParametersRequiredDescription
urlsRequiredRequired non-empty array of public Google Play ranking URLs. Every URL must use play.google.com or one of its subdomains and contain /store/apps/collection/ or /store/apps/category/ in its path; the runtime does not accept country or category as independent fields.
results_limitOptionalOptional positive integer from 1 to 2000. It defaults to 100, caps discovery and stored records across the whole task, and supplies the initial billing estimate. Input URLs are processed in order against the remaining task quota.

How to Use the Google Play App Rankings API

Submit one or more known Google Play chart URLs to the Google Play App Rankings API, follow the asynchronous task, and read normalized ranking records after success.

  1. Choose public play.google.com category or ranking URLs whose chart context already encodes the market and collection surface you need.
  2. POST urls and an optional results_limit to /v1/google-play/app-rankings, then save the returned task_id.
  3. Poll /v1/tasks/{task_id} until status is succeeded or failed; results are unavailable while the task is still queued or running.
  4. Read data.results.items and continue with next_cursor only when has_more is true.
curl -X POST "https://api.socq.ai/v1/google-play/app-rankings" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://play.google.com/store/apps/collection/topselling_free"],"results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?cursor={next_cursor}&limit=50

Google Play App Rankings API Use Cases

  • Category chart snapshots: Store the rank and collected_at from each Google Play App Rankings API run together to compare separately collected snapshots of a known chart.
  • Ranked app discovery: Turn a curated set of category URLs into normalized app records with the Google Play App Rankings API for review, tagging, or downstream catalog enrichment.
  • Portfolio position checks: Match available app_id and developer fields to an internal portfolio, then examine each returned position without relying on display-name matching alone.
  • Cross-run store analysis: Load the fixed AppItem fields into a warehouse so nullable ratings, review counts, installs, prices, and ranks remain comparable across collections.

Google Play App Rankings API Pro Tips

  • Use a public Google Play category or chart URL, not an app details page, search phrase, country code, or category label; only urls and results_limit belong in this request.
  • Use a play.google.com URL whose path contains /store/apps/collection/ or /store/apps/category/; app detail pages and unrelated paths fail validation before collection starts.
  • For multiple input URLs, results_limit is shared by the whole Google Play App Rankings API task. URLs are processed in order and each one receives only the remaining quota, so split tasks when every chart needs an independent quota.
  • Treat app metadata as nullable. Preserve app_id, url, rank, and collected_at when available instead of assuming ratings, review counts, installs, price, or media will always be populated.
  • Do not send a source cursor. Wait for success, then use only the opaque next_cursor returned inside data.results to page SocQ's stored records.
  • Budget from results_limit at submission time. Final credits follow the actual stored result count at 0.15 credits each, with unused estimated credits refunded.

Beyond the Google Play App Rankings API, use these APIs when you need a different type of public Google Play data.

  • Google Play App Detail API — Retrieve normalized public Google Play listing details from known app URLs, including identity, store copy, developer, category, visible metrics, price, media, and collection context.
  • Google Play App Reviews API — Collect public app reviews from play.google.com URLs with optional country context and normalized text, reviewer, rating, time, and app-reference fields.

Explore other platforms

Combine Google Play data with public data from other supported social platforms.

Google Play App Rankings API — FAQ

Google Play App Rankings API is a programmatic interface for collecting public Google Play category ranking URLs into normalized AppItem records with available rank, app identity, store metadata, media, source, and collection time.

Submit a non-empty array of public play.google.com ranking URLs. Subdomains are accepted, but every path must contain /store/apps/collection/ or /store/apps/category/; app detail pages and unrelated paths are rejected.

No. The request accepts urls and optional results_limit only, so market, collection, or category context must already be represented by the submitted Google Play URL.

results_limit accepts 1 through 2000 and defaults to 100. It caps discovery and stored results across the whole task and sets the initial result-count estimate used for precharge. Multiple URLs are processed in order against the remaining task quota.

No. The provider completes its dataset collection before SocQ exposes results; next_cursor only continues through normalized records already stored for a succeeded task.

The AppItem result includes fixed fields for ID, platform, resource, type, URL, timestamps, app_id, name, text, developer, category, rating, reviews_count, installs, price, rank, and media. Optional source values remain null when unavailable.

Billing is 0.15 SocQ credits per stored result with a zero-credit base. SocQ precharges from results_limit or the default estimate of 100, settles against the actual result count, and refunds the unused estimate; an empty result settles to zero.