# Google Play (/docs/google_play)

Google Play app search, app detail, user reviews, store charts, autocomplete suggestions, and a paginated listings database

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.

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

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

  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.

## Quickstart

### Turn an app name into a package name

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_play/app-search?query=photo%20editor&country=US" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read the full record and what users say

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_play/app-info?app_id=com.spotify.music" \
  -H "x-api-key: YOUR_API_KEY"

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: YOUR_API_KEY"
```

## Finding apps

| Endpoint                                  | Credits | What it returns                                                                                     | Key parameters                                                                                         |
| ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `GET /v1/google_play/app-search`          | 5       | Keyword matches with title, icon, developer, rating, price or free flag, store URL                  | `query` (required), `country`, `language`, `depth`                                                     |
| `GET /v1/google_play/app-listings-search` | 10      | The same app shape from a filterable listings database, with a store-wide total alongside each page | `title` (required), `description`, `limit`, `offset`, `offset_token`, `filters`, `country`, `language` |
| `GET /v1/google_play/search-suggestions`  | 1       | Play's own autocomplete terms for a partial keyword, each with its rank                             | `query` (required), `country`, `language`                                                              |

`app-listings-search` is the only Google Play endpoint with real pagination: `limit` runs 1 to 50, `offset` up to 10,000, and `offset_token` carries you past that. It also accepts a `filters` expression as a JSON array.

`search-suggestions` returns `{ term, priority }` ranked in Play's own order. Poll a stem daily and diff the list to catch a rising search before it moves the charts.

## App detail and reviews

| Endpoint                          | Credits | What it returns                                                                                                                     | Key parameters                                                           |
| --------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `GET /v1/google_play/app-info`    | 5       | Description, developer contact details, rating, price, install count, version, size, screenshots, genres, similar apps, update date | `app_id` (required), `country`, `language`                               |
| `GET /v1/google_play/app-reviews` | 5       | Star rating, full text, reviewer name and avatar, helpful-vote count, publish date, and the developer's reply where there is one    | `app_id` (required), `depth`, `sort_by`, `rating`, `country`, `language`, `label`, `judgments` |

Reviews 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

| Endpoint                       | Credits | What it returns                                                                  | Key parameters                                                              |
| ------------------------------ | ------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `GET /v1/google_play/app-list` | 5       | A store chart in the same app shape as search, optionally scoped to one category | `app_collection` (required), `app_category`, `depth`, `country`, `language` |

`app_collection` accepts `topselling_free`, `topselling_paid`, `topgrossing`, `movers_shakers`, `topselling_new_free` and `topselling_new_paid`. `depth` runs up to 500.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_play/app-list?app_collection=movers_shakers&country=KR" \
  -H "x-api-key: YOUR_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.

## Reference lookups

| Endpoint                         | Credits | What it returns                                         | Key parameters |
| -------------------------------- | ------- | ------------------------------------------------------- | -------------- |
| `GET /v1/google_play/categories` | 1       | The values `app_category` takes on `app-list`           | none           |
| `GET /v1/google_play/locations`  | 1       | Supported storefronts with their numeric location codes | none           |
| `GET /v1/google_play/languages`  | 1       | Supported language codes                                | none           |

Static reference data, cached hard. Call each once and keep the answer.

## All endpoints

## Platform notes

**Reviews are capped at 600.** No parameter raises that ceiling, and above 600 the request is clamped rather than rejected. Sample over time rather than trying to page past it. The Apple App Store's ceiling is lower, at 500.

**`depth` rounds UP to the store's native batch.** Search rounds to 30, reviews to 150 and charts to 100, so `depth=31` fetches 60 and `depth=150` on a chart fetches 200. The credit cost does not change with `depth`. Charts also stop where the store stops: `topselling_free` returns 100 at the default and 200 at `depth=500`.

**Play reviews carry no title.** That field is always null here because Play does not publish one, not because it was dropped. Apple reviews do have a title.

**Apple-only fields null out.** `app.store` is always `google_play`, and the leaves that only exist on Apple records, such as age advisories and supported languages, come back null.

**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`.

**`country` accepts three shapes on the app-data endpoints.** An ISO code (`US`), a full country name (`United States`), or a numeric location code (`2840`) all work there, and it defaults to the US. **`search-suggestions` is the exception:** it takes an ISO alpha-2 code only, and anything else is a free 400. Get the numeric codes from `locations`.

**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.

## Labels

`/v1/google_play/app-reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and where depth replaces it.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [API reference](/docs/api-reference.md): Every Google Play parameter and response field.
- [Apple App Store](/docs/app_store.md): The same endpoint names for the other store.
- [Trustpilot](/docs/trustpilot.md): Company reviews in the same canonical review shape.