# Google Play (/docs/google_play)



Google Play [#google-play]

Google Play store intelligence on a plain `GET`: keyword search, full app records with install
counts, user reviews including developer replies, the store charts, the autocomplete terms Play
suggests in its own search box, and a filterable listings database you can page deeply.
Everything is storefront-aware, so the same query answers differently per country.

Base URL: `/v1/google_play/...`

<Callout>
  Raising 

  `depth`

   on 

  `app-search`

   past its default rarely returns more: Play's organic keyword search typically exposes only about 30 ranked results however much you ask for. When you need to enumerate rather than sample, 

  `app-listings-search`

   is the endpoint with real pagination.
</Callout>

Every app read starts from the **package name** — `com.spotify.music`, the `id` parameter in a
`play.google.com/store/apps/details?id=…` URL. `app-search` is how you turn an app name into
one.

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header.

```bash
# 1. Name to package name (5 credits)
curl "https://www.socialcrawl.dev/v1/google_play/app-search?query=photo%20editor&country=US" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. The full record for one app (5 credits)
curl "https://www.socialcrawl.dev/v1/google_play/app-info?app_id=com.spotify.music" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 3. What its users say (5 credits)
curl "https://www.socialcrawl.dev/v1/google_play/app-reviews?app_id=com.spotify.music&sort_by=most_relevant&rating=1" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Finding apps [#finding-apps]

`app-search` returns keyword matches with title, icon, developer, rating, price or free flag and
store URL. Raising `depth` past its 30 default rarely helps: Play's organic keyword search
typically exposes only about 30 ranked results however much you ask for.

When you need to enumerate rather than sample, `/v1/google_play/app-listings-search` is the
endpoint with real pagination. It searches a listings database by `title`, optionally narrowed
by `description` text, and returns a total count across the whole store alongside each page.
`limit` runs 1-50, `offset` up to 10,000, and `offset_token` carries you past that. It also
accepts a DataForSEO `filters` expression as a JSON array. It costs 10 credits.

`/v1/google_play/search-suggestions` returns Play's own autocomplete terms for a partial
keyword, each with its rank, for 1 credit. Poll a stem daily and diff the list to catch a rising
search before it moves the charts.

App detail and reviews [#app-detail-and-reviews]

`app-info` returns what search results leave out: description, developer contact details,
rating, price, **install count**, version, size, screenshots and genres.

`app-reviews` returns user reviews with star rating, full text, reviewer name and avatar,
helpful-vote count, publish date, and the developer's reply where there is one. They arrive in
batches of 150 up to a ceiling of 600, `sort_by` selects `newest` (default) or `most_relevant`,
and `rating` filters to a single star value.

Charts [#charts]

`app-list` returns a store chart by name. `app_collection` accepts `topselling_free`,
`topselling_paid`, `topgrossing`, `movers_shakers`, `topselling_new_free` and
`topselling_new_paid`, and `app_category` scopes any of them to one category. `depth` runs up to
500\.

```bash
# What is climbing fastest among Korean Play users
curl "https://www.socialcrawl.dev/v1/google_play/app-list?app_collection=movers_shakers&country=KR" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

`movers_shakers` has no App Store equivalent — it is the one chart that reports change rather
than position, which makes it the cheapest early signal on this platform.

Taxonomy endpoints [#taxonomy-endpoints]

Three 1-credit endpoints describe what the others accept, and are worth calling once and
caching. `/v1/google_play/categories` lists the values `app_category` takes on `app-list`.
`/v1/google_play/locations` lists the supported storefronts with their numeric location codes.
`/v1/google_play/languages` lists the supported language codes.

Endpoints [#endpoints]

<PlatformEndpoints platform="google_play" />

Read this before you build [#read-this-before-you-build]

**`country` accepts three shapes.** An ISO code (`US`), a full country name (`United States`),
or a numeric location code (`2840`) all work, and it defaults to the US. Get the numeric codes
from `locations`.

**Storefront changes the answer, not just the language.** Ratings, review text, charts and
availability differ per country. A cross-market comparison means one call per country, not one
call with a different `language`.

**Reviews are capped at 600.** No parameter raises that ceiling — it is what Play exposes
publicly. Sample over time rather than trying to page past it.

**Cross-store comparison uses the same shapes.** [The Apple App Store](/docs/app_store.md) mirrors
this endpoint set with the same names, so one integration covers both stores. The identifier
differs: Apple uses a numeric id where Play uses a package name.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `app-search`, `app-info`, `app-reviews` and `app-list` are 5 credits; `app-listings-search` is
  10; the suggestion and taxonomy endpoints are 1
* `language` defaults to `en` everywhere and does not change which storefront is queried