# App store tools

Google Play and App Store listings, reviews, charts, and search rankings.

## Get an app

Tool: `apps_get_app`

One app's store listing. Use apps_search_apps or apps_get_top_charts to find ids. Read live; can take up to a minute.

Returns title, subtitle (App Store only), description, category, genres[], rating (of 5), ratings_count, installs (Google Play only), price (0 when free), currency, content_rating, version, released_at, updated_at, update_notes, developer, website, email and address (Google Play only), screenshots[], similar_apps[], more_by_developer[] (app_id, title). null = the store does not show it.

Cost: 1 credit. Cached 1 day.

Endpoint: `POST /api/apps/tools/apps_get_app`

Cost: 1 credit. Cached 1 day.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Required. Google Play: the package name as in the store URL (com.Slack). App Store: the numeric id (618783545)."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store",
    "app_id"
  ]
}
```

## Get app reviews

Tool: `apps_get_reviews`

User reviews of one app, newest first or most relevant. Read live; can take up to a minute.

Returns store, app_id, title, rating, ratings_count (all star ratings, most without text, so more than the reviews that can be fetched) and rows[]: id, rating, title (App Store only), text, author, published_at, app_version, helpful_count and developer_reply (Google Play only). meta.rows_available is set only when the call reached the end of what can be fetched.

Cost: 1 credit per 100 reviews. Default 100 = 1 credit. Cached 6 hours.

Endpoint: `POST /api/apps/tools/apps_get_reviews`

Cost: 1 credit per 100 reviews. Default 100 = 1 credit. Cached 6 hours.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Required. Google Play: the package name as in the store URL (com.Slack). App Store: the numeric id (618783545)."
    },
    "sort": {
      "default": "newest",
      "type": "string",
      "enum": [
        "newest",
        "most_relevant"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000; the App Store returns at most 500.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store",
    "app_id"
  ]
}
```

## Get an app's store keywords

Tool: `apps_get_keywords`

Store searches an app ranks for, with volume and position, best rank first. Keyword data covers the United States in English only. NoData means the store has no keyword data for the app; Google Play covers fewer apps than the App Store.

Returns rows[]: keyword, volume (monthly store searches), rank, results_count (apps in the store's results; the App Store counts at most about 250; null on Google Play).

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Endpoint: `POST /api/apps/tools/apps_get_keywords`

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Required. Google Play: the package name as in the store URL (com.Slack). App Store: the numeric id (618783545)."
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store",
    "app_id"
  ]
}
```

## Find competing apps

Tool: `apps_get_competitors`

Apps competing with one app for the same store searches; the app itself is left out. Returns ids only: call apps_get_app for names. Keyword data covers the United States in English only.

Returns rows[]: app_id, shared_keywords, avg_position, keywords (every store search it ranks for), top_3, keywords_volume.

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Endpoint: `POST /api/apps/tools/apps_get_competitors`

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Required. Google Play: the package name as in the store URL (com.Slack). App Store: the numeric id (618783545)."
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store",
    "app_id"
  ]
}
```

## Compare apps' keywords

Tool: `apps_get_shared_keywords`

Store searches all the given apps rank for, positions side by side, by volume. Keyword data covers the United States in English only.

Returns rows[]: keyword, volume, ranks[] (app_id, rank) in the order the apps were given.

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Endpoint: `POST /api/apps/tools/apps_get_shared_keywords`

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "app_ids": {
      "minItems": 2,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "description": "Required. Google Play: the package name as in the store URL (com.Slack). App Store: the numeric id (618783545)."
      },
      "description": "Required. 2 to 20 apps, all in one store."
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store",
    "app_ids"
  ]
}
```

## Search apps

Tool: `apps_search_apps`

Apps by title from an index of every app in a store, with listings and developer contacts. A match is any one word in the title, so search one distinctive word and add a category. Ordered biggest first (Google Play by installs, App Store by ratings), not by the store's search ranking.

Returns rows[]: app_id, title, subtitle, description (first 500 characters), category, rating, ratings_count, installs, price, developer, website, email.

Cost: 31 + 31 per 100 rows. Default 100 rows = 62 credits. Cached 7 days.

Endpoint: `POST /api/apps/tools/apps_search_apps`

Cost: 31 + 31 per 100 rows. Default 100 rows = 62 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. Matches when any one word appears in the title."
    },
    "category": {
      "description": "Store category, e.g. Business.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store",
    "query"
  ]
}
```

## Get a top chart

Tool: `apps_get_top_charts`

A store's chart, overall or within one category, in chart order. A wrong category id is refused at no charge. Read live; can take up to a minute.

Returns rows[]: rank, app_id, title, url, developer (Google Play only), rating, ratings_count (App Store only), is_free, price, currency.

Cost: 1 credit per 100 rows. Default 100 = 1 credit. Cached 1 day.

Endpoint: `POST /api/apps/tools/apps_get_top_charts`

Cost: 1 credit per 100 rows. Default 100 = 1 credit. Cached 1 day.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "google_play",
        "app_store"
      ],
      "description": "Required. google_play or app_store."
    },
    "chart": {
      "default": "top_free",
      "type": "string",
      "enum": [
        "top_free",
        "top_paid",
        "top_grossing",
        "new_free",
        "new_paid"
      ]
    },
    "category": {
      "description": "Category id such as health_and_fitness; names like \"Health & Fitness\" are converted. Omit for all categories.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "limit": {
      "default": 100,
      "description": "Default 100; Google Play up to 200, App Store up to 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "store"
  ]
}
```