> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/google-play.md).

# Google Play

Google Play Store: app lookup, search, similar apps, reviews, permissions, and data safety. All endpoints are read-only `GET` requests and return public Google Play data — no app of your own is required.

**Base URL:** `https://dashboard.pullbay.com/api`

## Endpoints

| Endpoint                       | Description                            | Pagination        |
| ------------------------------ | -------------------------------------- | ----------------- |
| `GET /google-play/apps`        | Get a single app by App ID             | —                 |
| `GET /google-play/search`      | Search apps by term                    | —                 |
| `GET /google-play/similar`     | Get apps similar to a given app        | —                 |
| `GET /google-play/reviews`     | Get reviews for an app                 | Cursor / maxItems |
| `GET /google-play/permissions` | Get permissions requested by an app    | —                 |
| `GET /google-play/data-safety` | Get the Data Safety section for an app | —                 |

***

## Get App

Returns full details for a single app on the Google Play Store, identified by its package name.

**Request**

```http
GET /google-play/apps
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `appId`   | string | Yes      | Package name, max 255 characters, letters/digits/`.`/`_` only (e.g. `com.instagram.android`) |
| `country` | string | No       | 2-letter ISO country code for the storefront (e.g. `us`)                                     |
| `lang`    | string | No       | Language code for localized text (e.g. `en`, `en-us`)                                        |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-play/apps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d appId=com.instagram.android \
  -d country=us
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "Instagram",
      "appId": "com.instagram.android",
      "url": "/api/apps/com.instagram.android",
      "icon": "https://play-lh.googleusercontent.com/VRMWkE5p3CkWhJs6nv-9ZsLAs1QOg5ob1_3qg-rckwYW7yp1fMrYZqnEFpk0IoVP4LM",
      "headerImage": "https://play-lh.googleusercontent.com/CgUPurtUp8SB709wsQcKLMv6JdIh1em0ka_58V69AorznLv42TV39etS2rt28wv9Rz8",
      "summary": "Create & share photos, stories, & reels with friends you love",
      "description": "Little moments lead to big friendships. Share yours on Instagram.",
      "descriptionHTML": "Little moments lead to big friendships. Share yours on Instagram. <br>—From Meta",
      "score": 4.0182447,
      "scoreText": "4.0",
      "ratings": 167461256,
      "reviews": 4568306,
      "histogram": { "1": 30279668, "2": 5233417, "3": 7039797, "4": 13507336, "5": 111401011 },
      "free": true,
      "price": 0,
      "priceText": "Free",
      "currency": "USD",
      "offersIAP": true,
      "adSupported": true,
      "installs": "5,000,000,000+",
      "minInstalls": 5000000000,
      "maxInstalls": 7427343782,
      "androidVersion": "VARY",
      "androidVersionText": "Varies with device",
      "updated": 1777328205000,
      "genre": "Social",
      "genreId": "SOCIAL",
      "developer": "Instagram",
      "developerId": "Instagram",
      "developerEmail": "instagram-android@meta.com",
      "developerWebsite": "http://help.instagram.com/",
      "developerInternalID": "Instagram",
      "privacyPolicy": "http://instagram.com/legal/privacy/",
      "playstoreUrl": "https://play.google.com/store/apps/details?id=com.instagram.android&hl=en&gl=us",
      "screenshots": ["https://play-lh.googleusercontent.com/hZ2Ob6d0MqLse2lIdNOGgl93H5y82uhX4hC6mWDUpdwK8LjXAunweDQZ6Hocy0riv4KX0lTIzKJz6lhRDV_BiHg"]
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Search Apps

Search the Google Play Store for apps matching a term. Returns lightweight summaries.

**Request**

```http
GET /google-play/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                  |
| --------- | ------ | -------- | -------------------------------------------- |
| `search`  | string | Yes      | Search term, 1–255 characters                |
| `price`   | string | No       | Filter by pricing: `all`, `free`, or `paid`  |
| `country` | string | No       | 2-letter ISO country code for the storefront |
| `lang`    | string | No       | Language code for localized text             |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-play/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d search="photo editor" \
  -d price=free \
  -d country=us
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "Instagram",
      "appId": "com.instagram.android",
      "url": "/api/apps/com.instagram.android",
      "icon": "https://play-lh.googleusercontent.com/VRMWkE5p3CkWhJs6nv-9ZsLAs1QOg5ob1_3qg-rckwYW7yp1fMrYZqnEFpk0IoVP4LM",
      "summary": "Create &amp; share photos, stories, &amp; reels with friends you love",
      "score": 4.0182447,
      "scoreText": "4.0",
      "free": true,
      "price": 0,
      "currency": "USD",
      "playstoreUrl": "https://play.google.com/store/apps/details?id=com.instagram.android",
      "developer": "Instagram",
      "developerId": "Instagram"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of results returned, not the number of requests.

***

## Get Similar Apps

Returns apps Google Play surfaces as similar to the supplied app.

**Request**

```http
GET /google-play/similar
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `appId`   | string | Yes      | Package name, max 255 characters, letters/digits/`.`/`_` only |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-play/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d appId=com.instagram.android
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "Instagram",
      "appId": "com.instagram.android",
      "url": "/api/apps/com.instagram.android",
      "icon": "https://play-lh.googleusercontent.com/VRMWkE5p3CkWhJs6nv-9ZsLAs1QOg5ob1_3qg-rckwYW7yp1fMrYZqnEFpk0IoVP4LM",
      "summary": "Create &amp; share photos, stories, &amp; reels with friends you love",
      "score": 4.0182447,
      "scoreText": "4.0",
      "free": true,
      "price": 0,
      "currency": "USD",
      "playstoreUrl": "https://play.google.com/store/apps/details?id=com.instagram.android",
      "developer": "Instagram",
      "developerId": "Instagram"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Get Reviews

Returns reviews for an app. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```http
GET /google-play/reviews
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `appId`    | string  | Yes      | Package name, max 255 characters, letters/digits/`.`/`_` only                         |
| `country`  | string  | No       | 2-letter ISO country code for the storefront                                          |
| `lang`     | string  | No       | Language code for localized text                                                      |
| `sort`     | string  | No       | `NEWEST`, `RATING`, or `HELPFULNESS`                                                  |
| `cursor`   | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–500 results. Mutually exclusive with `cursor`                   |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-play/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d appId=com.instagram.android \
  -d country=us \
  -d sort=NEWEST
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "045b1b4e-b207-40f7-8a9e-d4e81664965e",
      "userName": "Jane Doe",
      "userImage": "https://example.com/reviewer-photo.jpg",
      "date": "2025-01-12T22:37:55.959Z",
      "score": 1,
      "scoreText": "1",
      "url": "https://play.google.com/store/apps/details?id=com.instagram.android&reviewId=045b1b4e-b207-40f7-8a9e-d4e81664965e",
      "title": null,
      "text": "The new update is so buggy.",
      "replyDate": null,
      "replyText": null,
      "version": "362.0.0.33.241",
      "thumbsUp": 10224,
      "country": "US",
      "criterias": [
        { "criteria": "vaf_mark_message_as_read", "rating": 1 }
      ]
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of reviews returned, not the number of requests.

***

## Get Permissions

Returns the list of Android permissions the app requests, grouped by category.

**Request**

```http
GET /google-play/permissions
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `appId`   | string | Yes      | Package name, max 255 characters, letters/digits/`.`/`_` only |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-play/permissions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d appId=com.instagram.android
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    { "permission": "find accounts on the device", "type": "Identity" }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Get Data Safety

Returns the developer-declared Data Safety information: data shared, data collected, security practices, and privacy policy URL.

**Request**

```http
GET /google-play/data-safety
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `appId`   | string | Yes      | Package name, max 255 characters, letters/digits/`.`/`_` only |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-play/data-safety" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d appId=com.instagram.android
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "sharedData": [
        { "data": "Name", "purpose": "Fraud prevention, security, and compliance", "type": "Personal info", "optional": false }
      ],
      "collectedData": [
        { "data": "Name", "purpose": "Fraud prevention, security, and compliance", "type": "Personal info", "optional": false }
      ],
      "securityPractices": [
        { "practice": "Data is encrypted in transit", "description": "Your data is transferred over a secure connection" }
      ],
      "privacyPolicyUrl": "http://instagram.com/legal/privacy/"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Object schemas

### Application object

| Field                                                                                       | Type                               | Description                                     |
| ------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------- |
| `title`                                                                                     | string                             | App name                                        |
| `appId`                                                                                     | string                             | Package name                                    |
| `url`                                                                                       | string                             | Relative API URL for the app detail endpoint    |
| `icon`                                                                                      | string                             | Icon image URL                                  |
| `headerImage`                                                                               | string                             | Feature graphic image URL                       |
| `summary`                                                                                   | string                             | Short tagline shown on the store listing        |
| `description` / `descriptionHTML`                                                           | string                             | Full description, plain text and HTML           |
| `score` / `scoreText`                                                                       | number / string                    | Average rating, numeric and display string      |
| `ratings` / `reviews`                                                                       | integer                            | Total rating count and total review count       |
| `histogram`                                                                                 | object                             | Rating counts keyed by star value (`1`–`5`)     |
| `free` / `price` / `priceText` / `currency`                                                 | boolean / number / string / string | Pricing info                                    |
| `offersIAP`                                                                                 | boolean                            | Whether the app offers in-app purchases         |
| `adSupported`                                                                               | boolean                            | Whether the app shows ads                       |
| `installs` / `minInstalls` / `maxInstalls`                                                  | string / integer / integer         | Install count range, display and numeric bounds |
| `androidVersion` / `androidVersionText`                                                     | string                             | Minimum Android version, raw and display form   |
| `updated`                                                                                   | integer                            | Last update timestamp (Unix ms)                 |
| `genre` / `genreId`                                                                         | string                             | Category name and ID                            |
| `developer` / `developerId` / `developerEmail` / `developerWebsite` / `developerInternalID` | string                             | Developer identity and contact info             |
| `privacyPolicy`                                                                             | string                             | Developer's privacy policy URL                  |
| `playstoreUrl`                                                                              | string                             | Public Google Play listing URL                  |
| `screenshots`                                                                               | array                              | Screenshot image URLs                           |

### Application summary object

Lightweight app reference returned by search and similar-apps endpoints.

| Field                         | Type                      | Description                                  |
| ----------------------------- | ------------------------- | -------------------------------------------- |
| `title`                       | string                    | App name                                     |
| `appId`                       | string                    | Package name                                 |
| `url`                         | string                    | Relative API URL for the app detail endpoint |
| `icon`                        | string                    | Icon image URL                               |
| `summary`                     | string                    | Short tagline shown on the store listing     |
| `score` / `scoreText`         | number / string           | Average rating, numeric and display string   |
| `free` / `price` / `currency` | boolean / number / string | Pricing info                                 |
| `playstoreUrl`                | string                    | Public Google Play listing URL               |
| `developer` / `developerId`   | string                    | Developer name and ID                        |

### Review object

| Field                     | Type                      | Description                                                      |
| ------------------------- | ------------------------- | ---------------------------------------------------------------- |
| `id`                      | string                    | Review ID                                                        |
| `userName`                | string                    | Reviewer's display name                                          |
| `userImage`               | string                    | Reviewer's avatar URL                                            |
| `date`                    | string (date-time)        | When the review was posted                                       |
| `score` / `scoreText`     | integer / string          | Rating, 1–5, numeric and display string                          |
| `url`                     | string                    | Permalink to the review                                          |
| `title`                   | string, nullable          | Review title (often absent on Google Play)                       |
| `text`                    | string                    | Review body                                                      |
| `replyDate` / `replyText` | string / string, nullable | Developer's reply timestamp and text, if any                     |
| `version`                 | string                    | App version the review was left for                              |
| `thumbsUp`                | integer                   | Helpful-vote count                                               |
| `country`                 | string                    | Storefront country the review was posted on                      |
| `criterias`               | array of Review criteria  | Rating breakdown by sub-criteria, if the developer collects them |

### Review criteria object

| Field      | Type    | Description                                                            |
| ---------- | ------- | ---------------------------------------------------------------------- |
| `criteria` | string  | Internal name of the rated criterion (e.g. `vaf_mark_message_as_read`) |
| `rating`   | integer | Rating given for that specific criterion                               |

### Permission object

| Field        | Type   | Description                                                                |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `permission` | string | Human-readable permission description (e.g. `find accounts on the device`) |
| `type`       | string | Permission category (e.g. `Identity`, `Location`)                          |

### Data Safety object

| Field               | Type                       | Description                            |
| ------------------- | -------------------------- | -------------------------------------- |
| `sharedData`        | array of Data Safety item  | Data types shared with third parties   |
| `collectedData`     | array of Data Safety item  | Data types collected by the app        |
| `securityPractices` | array of Security practice | Declared security practices            |
| `privacyPolicyUrl`  | string                     | Link to the developer's privacy policy |

### Data Safety item object

| Field      | Type    | Description                                       |
| ---------- | ------- | ------------------------------------------------- |
| `data`     | string  | Type of data (e.g. `Name`)                        |
| `purpose`  | string  | Stated purpose for collecting or sharing the data |
| `type`     | string  | Data category (e.g. `Personal info`)              |
| `optional` | boolean | Whether providing this data is optional           |

### Security practice object

| Field         | Type   | Description                                                         |
| ------------- | ------ | ------------------------------------------------------------------- |
| `practice`    | string | Name of the security practice (e.g. `Data is encrypted in transit`) |
| `description` | string | Explanation of the practice                                         |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | App or review set not found              |

## Finding App IDs

* **App ID**: the Android package name, visible in a Google Play URL, e.g. `https://play.google.com/store/apps/details?id=com.instagram.android` → `com.instagram.android`.
* Package names are dot-separated identifiers made up of letters, digits, periods, and underscores — there is no separate numeric ID like on the App Store.

## Pagination Notes

* `/google-play/reviews` is the only paginated endpoint in this service. It uses **cursor-based** pagination: pass the `cursor` value from a previous response's `pagination.cursor` field to fetch the next page.
* Alternatively, use `maxItems` for a one-shot bulk pull of up to 500 reviews in a single call. `cursor` and `maxItems` are mutually exclusive — pick one strategy per request.
* All other endpoints in this service return a complete result set in one call and have no pagination parameters.

## Country and Language Codes

* `country` accepts any 2-letter ISO 3166-1 alpha-2 storefront code (`us`, `gb`, `jp`, `de`, ...).
* `lang` accepts a 2–3 letter ISO 639 language code, optionally with a region subtag (`en`, `en-us`, `pt-br`).
* If omitted, both default to the US storefront in English.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/google-play.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.