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.
Features
- Chart URL batchesSubmit 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.
Parameters
| Parameters | Required | Description |
|---|---|---|
urls | Required | Required 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_limit | Optional | Optional 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
Submit one or more known Google Play chart URLs, follow the asynchronous task, and read normalized ranking records after success.
- Choose public play.google.com category or ranking URLs whose chart context already encodes the market and collection surface you need.
- POST urls and an optional results_limit to /v1/google-play/app-rankings, then save the returned task_id.
- Poll /v1/tasks/{task_id} until status is succeeded or failed; results are unavailable while the task is still queued or running.
- 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=50Best Use Cases
- Category chart snapshots: Store rank and collected_at together to compare separately collected snapshots of a known Google Play chart.
- Ranked app discovery: Turn a curated set of category URLs into normalized app records 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.
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 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.
Related APIs
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.