{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Play Store Scraper — App Search, Reviews & ASO Charts",
    "description": "Scrape Google Play Store app data, reviews and ASO competitive charts in one run. App search, full app details, reviews, category list and all 6 top-charts — top free, paid and grossing apps & games, category-filterable. Clean structured JSON, pay per result.",
    "version": "1.0",
    "x-build-id": "NxppPHwJRLNyZSVYB"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~play-store-apps-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-play-store-apps-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~play-store-apps-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-play-store-apps-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~play-store-apps-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-play-store-apps-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "operation"
        ],
        "properties": {
          "operation": {
            "title": "🎯 Operation — what do you want to scrape?",
            "enum": [
              "search",
              "topCharts",
              "appDetails",
              "appReviews",
              "categories"
            ],
            "type": "string",
            "description": "🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode.\n\n- **🔍 App Search** — search Google Play by keyword, paginated (~20 apps/page)\n- **📊 Top Charts** — pull a Google Play top-chart (free / paid / grossing × apps / games), category-filterable\n- **📱 App Details** — full details for one app by its App ID (paid plan)\n- **⭐ App Reviews** — reviews for one app, paginated (paid plan)\n- **🗂️ Categories** — the full Google Play category list (free)\n\n💡 **TIP:** Run App Search or Top Charts first to discover App IDs, then drill into App Details / Reviews.",
            "default": "search"
          },
          "query": {
            "title": "🔍 Search Query (for App Search)",
            "type": "string",
            "description": "🔍 **Required for `App Search` operation.**\n\nA free-form keyword query — exactly what you would type into the Play Store search bar.\n- `fitness tracker`\n- `photo editor`\n- `language learning`\n\n💡 **TIP:** Use specific keywords to surface a tight set of competing apps for ASO research.\n\n⚠️ **Ignored** for all other operations."
          },
          "chartType": {
            "title": "📊 Chart Type (for Top Charts)",
            "enum": [
              "top-free-apps",
              "top-paid-apps",
              "top-grossing-apps",
              "top-free-games",
              "top-paid-games",
              "top-grossing-games"
            ],
            "type": "string",
            "description": "📊 **Required for `Top Charts` operation.**\n\nWhich Google Play top-chart to pull:\n- `top-free-apps` — Top Free apps\n- `top-paid-apps` — Top Paid apps\n- `top-grossing-apps` — Top Grossing apps\n- `top-free-games` — Top Free games\n- `top-paid-games` — Top Paid games\n- `top-grossing-games` — Top Grossing games\n\n💡 **TIP:** Combine with the `Category` filter below to chart a single Play Store category.\n\n⚠️ **Ignored** for all other operations.",
            "default": "top-free-apps"
          },
          "category": {
            "title": "🗂️ Category (for Top Charts)",
            "type": "string",
            "description": "Optional. Filter a Top Chart to a single Google Play category by its ID (e.g. `GAME`, `GAME_PUZZLE`, `MUSIC_AND_AUDIO`, `PRODUCTIVITY`).\n\n💡 **TIP:** Run the `Categories` operation first to get the full list of valid category IDs.\n\n⚠️ Only used for Top Charts."
          },
          "appId": {
            "title": "📱 App ID (for App Details & Reviews)",
            "type": "string",
            "description": "📱 **Required for `App Details` and `App Reviews`.**\n\nThe Google Play package name / App ID (e.g. `com.spotify.music`, `com.instagram.android`). This is the `appId` field from a search or chart result row, and the `id=` value in a Play Store URL.\n\n💡 **TIP:** Run App Search or Top Charts first to collect `appId` values, then loop through App Details / Reviews.\n\n⚠️ **Ignored** for all other operations."
          },
          "sortBy": {
            "title": "🔀 Review Sort (for App Reviews)",
            "enum": [
              "MOST_RELEVANT",
              "NEWEST",
              "RATING"
            ],
            "type": "string",
            "description": "Optional. Order for `App Reviews`.\n\n- `MOST_RELEVANT` (default)\n- `NEWEST`\n- `RATING`\n\n⚠️ Only used for App Reviews.",
            "default": "MOST_RELEVANT"
          },
          "rating": {
            "title": "⭐ Filter by Star Rating (for App Reviews)",
            "enum": [
              "ANY",
              "ONE_STAR",
              "TWO_STARS",
              "THREE_STARS",
              "FOUR_STARS",
              "FIVE_STARS"
            ],
            "type": "string",
            "description": "Optional. Return only reviews with this star rating for `App Reviews`. `ANY` returns all ratings.\n\n⚠️ Only used for App Reviews.",
            "default": "ANY"
          },
          "country": {
            "title": "🌍 Region / Country",
            "type": "string",
            "description": "🌍 ISO 3166-1 alpha-2 country code for the Play Store region (e.g. `us`, `gb`, `de`, `in`, `br`). Default `us`.\n\nApplies to all operations except Categories."
          },
          "language": {
            "title": "🗣️ Language",
            "type": "string",
            "description": "Optional. ISO 639 language code for results (e.g. `en`, `es`, `de`, `pt`). Defaults to the region's primary language."
          },
          "limit": {
            "title": "🔢 Results per request",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Optional. Number of rows to request per page (App Search, Top Charts, App Reviews). Higher values reduce upstream calls. Leave blank for the source default.\n\n💡 **TIP:** App Reviews and Top Charts support up to 50 per request."
          },
          "maxPages": {
            "title": "📄 Max pages to fetch",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "📄 **Applies to `App Search` and `App Reviews` only.** Ignored for single-record operations.\n\n💡 **TIP:** Start small (1–3 pages) to preview results before scaling up. Pagination stops automatically when the data source reports no more results.\n\n⚠️ Hard cap: 20 pages to prevent runaway runs.",
            "default": 3
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}