{
  "openapi": "3.0.3",
  "info": {
    "title": "Google Play Apps, Reviews & Trust Data (server mode)",
    "version": "1.1",
    "description": "Send one lookup and get the results back in the response. It takes the same input as a normal run: query parameters with GET, or a JSON body with POST. At most 100 results and 240 seconds per request; start a normal run for bigger jobs. Requests run in your own Apify account at the Actor's normal price.",
    "x-oa-server-mode": "1.1"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "lookupGet",
        "summary": "Run one lookup (query parameters)",
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "required": true,
            "description": "What to scrape.",
            "schema": {
              "type": "string",
              "enum": [
                "search",
                "details",
                "reviews",
                "developer",
                "similar",
                "permissions",
                "dataSafety"
              ],
              "default": "search"
            },
            "example": "search"
          },
          {
            "name": "searchQuery",
            "in": "query",
            "required": false,
            "description": "Keyword to search for in mode=search, for example `photo editor` or `calculator`.",
            "schema": {
              "type": "string",
              "default": "calculator"
            },
            "example": "calculator"
          },
          {
            "name": "appIds",
            "in": "query",
            "required": false,
            "description": "Package names or Google Play URLs. Used by details, reviews, similar, permissions, and dataSafety modes. (GET: repeat the parameter once per value.)",
            "schema": {
              "type": "array",
              "default": [],
              "items": {
                "type": "string"
              },
              "maxItems": 10
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "packageNames",
            "in": "query",
            "required": false,
            "description": "Android package names such as `com.whatsapp`. Play URLs are also accepted. (GET: repeat the parameter once per value.)",
            "schema": {
              "type": "array",
              "default": [],
              "items": {
                "type": "string"
              },
              "maxItems": 10
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "startUrls",
            "in": "query",
            "required": false,
            "description": "Full Google Play app URLs, for example `https://play.google.com/store/apps/details?id=com.whatsapp`. (GET: repeat the parameter once per value.)",
            "schema": {
              "type": "array",
              "default": [],
              "items": {
                "type": "string"
              },
              "maxItems": 10
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "developerId",
            "in": "query",
            "required": false,
            "description": "Numeric Google Play developer ID or a developer page URL, used in mode=developer.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "developerName",
            "in": "query",
            "required": false,
            "description": "Display name shown on Google Play, for example `Google LLC`, used in mode=developer.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Storefront for search results, pricing, and availability. Reviews are selected by Language, not Country.",
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "gb",
                "ca",
                "au",
                "in",
                "de",
                "fr",
                "es",
                "it",
                "jp",
                "kr",
                "br",
                "mx",
                "nl",
                "be",
                "at",
                "ch",
                "se",
                "no",
                "dk",
                "fi",
                "pl",
                "pt",
                "cz",
                "ro",
                "hu",
                "gr",
                "tr",
                "ru",
                "ua",
                "za",
                "eg",
                "ng",
                "ke",
                "id",
                "th",
                "vn",
                "ph",
                "my",
                "sg",
                "tw",
                "hk",
                "nz",
                "ar",
                "cl",
                "co",
                "pe",
                "il",
                "ae",
                "sa"
              ],
              "default": "us"
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Language for app pages and the review bucket. Google Play uses this language, not Country, to choose reviews.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "de",
                "it",
                "pt",
                "ja",
                "ko",
                "zh",
                "ru",
                "ar",
                "hi",
                "th",
                "vi",
                "id",
                "tr",
                "pl",
                "nl",
                "sv",
                "da",
                "no",
                "fi",
                "cs",
                "ro",
                "hu",
                "el",
                "he",
                "uk",
                "ms",
                "tl"
              ],
              "default": "en"
            }
          },
          {
            "name": "maxItems",
            "in": "query",
            "required": false,
            "description": "Hard cap on dataset rows. Search returns at most 250 apps per query. For similar mode one seed app is one row.",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 50
            },
            "example": 3
          },
          {
            "name": "maxReviewsPerApp",
            "in": "query",
            "required": false,
            "description": "Reviews to collect for each app. Google Play returns at most 4,500 reviews per page; the actor paginates up to this cap.",
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "reviewSort",
            "in": "query",
            "required": false,
            "description": "Order used when fetching reviews.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "rating",
                "helpfulness"
              ],
              "default": "newest"
            }
          },
          {
            "name": "includeDetails",
            "in": "query",
            "required": false,
            "description": "Fetch the full app page for search and developer results, and include app metadata in permissions/dataSafety output. Adds one request per app.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "includePermissions",
            "in": "query",
            "required": false,
            "description": "Add the app's permission list to app records. Works in search, details, developer, and similar modes.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "includeDataSafety",
            "in": "query",
            "required": false,
            "description": "Add shared data, collected data, security practices, and the privacy policy URL to app records.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "proxyConfiguration",
            "in": "query",
            "required": false,
            "description": "Optional. The actor works without a proxy; use one only if Google Play blocks your runs. (GET: pass it as JSON.)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The results as a JSON array (at most 100). They are also saved to the run's dataset and billed per result, like a normal run.",
            "headers": {
              "X-Item-Count": {
                "schema": {
                  "type": "integer"
                },
                "description": "Results returned."
              },
              "X-Status-Message": {
                "schema": {
                  "type": "string"
                },
                "description": "The Actor's last status message, e.g. why nothing was found."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Item"
                  }
                },
                "example": [
                  {
                    "packageName": "com.sec.android.app.popupcalculator",
                    "appId": "com.sec.android.app.popupcalculator",
                    "id": "com.sec.android.app.popupcalculator",
                    "name": "Samsung Calculator",
                    "title": "Samsung Calculator",
                    "url": "https://play.google.com/store/apps/details?id=com.sec.android.app.popupcalculator",
                    "sourceUrl": "https://play.google.com/store/apps/details?id=com.sec.android.app.popupcalculator",
                    "summary": "[Key features]\nPerform four fundamental operations and engineering calculations.\n\nTo start the engineering calculator, tap the engineering calculator icon.\n\n...",
                    "developer": "Samsung Electronics Co.,  Ltd.",
                    "developerUrl": "https://play.google.com/store/apps/developer?id=Samsung+Electronics+Co.%2C++Ltd.",
                    "rating": 4.45,
                    "score": 4.45,
                    "scoreText": "4.5",
                    "icon": "https://play-lh.googleusercontent.com/p8rUJZjn-oJQPhrNASuJEZu3njkIxXP6P_AdeSUrXl5BrrtZDBu_YUBxJp0_WgcsaQ5HnB5-j9Fa7whGc0vo6w",
                    "price": 0,
                    "currency": "USD",
                    "free": true,
                    "searchQuery": "calculator",
                    "rank": 1,
                    "isExactMatch": false,
                    "recordType": "app",
                    "language": "en",
                    "country": "us",
                    "scrapedAt": "2026-11-10T15:33:11.818504+00:00"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid, missing or unknown input fields. Nothing ran.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_input",
                  "errorDescription": "mode: required"
                }
              }
            }
          },
          "422": {
            "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected failure. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The request used up its 240 s budget. The results found so far are in partialItems.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "partialItems": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Item"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "lookupPost",
        "summary": "Run one lookup (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "search",
                      "details",
                      "reviews",
                      "developer",
                      "similar",
                      "permissions",
                      "dataSafety"
                    ],
                    "default": "search",
                    "description": "What to scrape."
                  },
                  "searchQuery": {
                    "type": "string",
                    "default": "calculator",
                    "description": "Keyword to search for in mode=search, for example `photo editor` or `calculator`."
                  },
                  "appIds": {
                    "type": "array",
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 10,
                    "description": "Package names or Google Play URLs. Used by details, reviews, similar, permissions, and dataSafety modes."
                  },
                  "packageNames": {
                    "type": "array",
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 10,
                    "description": "Android package names such as `com.whatsapp`. Play URLs are also accepted."
                  },
                  "startUrls": {
                    "type": "array",
                    "default": [],
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 10,
                    "description": "Full Google Play app URLs, for example `https://play.google.com/store/apps/details?id=com.whatsapp`."
                  },
                  "developerId": {
                    "type": "string",
                    "description": "Numeric Google Play developer ID or a developer page URL, used in mode=developer."
                  },
                  "developerName": {
                    "type": "string",
                    "description": "Display name shown on Google Play, for example `Google LLC`, used in mode=developer."
                  },
                  "country": {
                    "type": "string",
                    "enum": [
                      "us",
                      "gb",
                      "ca",
                      "au",
                      "in",
                      "de",
                      "fr",
                      "es",
                      "it",
                      "jp",
                      "kr",
                      "br",
                      "mx",
                      "nl",
                      "be",
                      "at",
                      "ch",
                      "se",
                      "no",
                      "dk",
                      "fi",
                      "pl",
                      "pt",
                      "cz",
                      "ro",
                      "hu",
                      "gr",
                      "tr",
                      "ru",
                      "ua",
                      "za",
                      "eg",
                      "ng",
                      "ke",
                      "id",
                      "th",
                      "vn",
                      "ph",
                      "my",
                      "sg",
                      "tw",
                      "hk",
                      "nz",
                      "ar",
                      "cl",
                      "co",
                      "pe",
                      "il",
                      "ae",
                      "sa"
                    ],
                    "default": "us",
                    "description": "Storefront for search results, pricing, and availability. Reviews are selected by Language, not Country."
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "es",
                      "fr",
                      "de",
                      "it",
                      "pt",
                      "ja",
                      "ko",
                      "zh",
                      "ru",
                      "ar",
                      "hi",
                      "th",
                      "vi",
                      "id",
                      "tr",
                      "pl",
                      "nl",
                      "sv",
                      "da",
                      "no",
                      "fi",
                      "cs",
                      "ro",
                      "hu",
                      "el",
                      "he",
                      "uk",
                      "ms",
                      "tl"
                    ],
                    "default": "en",
                    "description": "Language for app pages and the review bucket. Google Play uses this language, not Country, to choose reviews."
                  },
                  "maxItems": {
                    "type": "integer",
                    "default": 50,
                    "minimum": 1,
                    "maximum": 50,
                    "description": "Hard cap on dataset rows. Search returns at most 250 apps per query. For similar mode one seed app is one row."
                  },
                  "maxReviewsPerApp": {
                    "type": "integer",
                    "default": 100,
                    "minimum": 1,
                    "maximum": 100,
                    "description": "Reviews to collect for each app. Google Play returns at most 4,500 reviews per page; the actor paginates up to this cap."
                  },
                  "reviewSort": {
                    "type": "string",
                    "enum": [
                      "newest",
                      "rating",
                      "helpfulness"
                    ],
                    "default": "newest",
                    "description": "Order used when fetching reviews."
                  },
                  "includeDetails": {
                    "type": "boolean",
                    "default": false,
                    "description": "Fetch the full app page for search and developer results, and include app metadata in permissions/dataSafety output. Adds one request per app."
                  },
                  "includePermissions": {
                    "type": "boolean",
                    "default": false,
                    "description": "Add the app's permission list to app records. Works in search, details, developer, and similar modes."
                  },
                  "includeDataSafety": {
                    "type": "boolean",
                    "default": false,
                    "description": "Add shared data, collected data, security practices, and the privacy policy URL to app records."
                  },
                  "proxyConfiguration": {
                    "type": "object",
                    "description": "Optional. The actor works without a proxy; use one only if Google Play blocks your runs."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "mode"
                ]
              },
              "example": {
                "mode": "search",
                "searchQuery": "calculator",
                "maxItems": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The results as a JSON array (at most 100). They are also saved to the run's dataset and billed per result, like a normal run.",
            "headers": {
              "X-Item-Count": {
                "schema": {
                  "type": "integer"
                },
                "description": "Results returned."
              },
              "X-Status-Message": {
                "schema": {
                  "type": "string"
                },
                "description": "The Actor's last status message, e.g. why nothing was found."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Item"
                  }
                },
                "example": [
                  {
                    "packageName": "com.sec.android.app.popupcalculator",
                    "appId": "com.sec.android.app.popupcalculator",
                    "id": "com.sec.android.app.popupcalculator",
                    "name": "Samsung Calculator",
                    "title": "Samsung Calculator",
                    "url": "https://play.google.com/store/apps/details?id=com.sec.android.app.popupcalculator",
                    "sourceUrl": "https://play.google.com/store/apps/details?id=com.sec.android.app.popupcalculator",
                    "summary": "[Key features]\nPerform four fundamental operations and engineering calculations.\n\nTo start the engineering calculator, tap the engineering calculator icon.\n\n...",
                    "developer": "Samsung Electronics Co.,  Ltd.",
                    "developerUrl": "https://play.google.com/store/apps/developer?id=Samsung+Electronics+Co.%2C++Ltd.",
                    "rating": 4.45,
                    "score": 4.45,
                    "scoreText": "4.5",
                    "icon": "https://play-lh.googleusercontent.com/p8rUJZjn-oJQPhrNASuJEZu3njkIxXP6P_AdeSUrXl5BrrtZDBu_YUBxJp0_WgcsaQ5HnB5-j9Fa7whGc0vo6w",
                    "price": 0,
                    "currency": "USD",
                    "free": true,
                    "searchQuery": "calculator",
                    "rank": 1,
                    "isExactMatch": false,
                    "recordType": "app",
                    "language": "en",
                    "country": "us",
                    "scrapedAt": "2026-11-10T15:33:11.818504+00:00"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid, missing or unknown input fields. Nothing ran.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "invalid_input",
                  "errorDescription": "mode: required"
                }
              }
            }
          },
          "422": {
            "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected failure. Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The request used up its 240 s budget. The results found so far are in partialItems.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "partialItems": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Item"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Item": {
        "type": "object",
        "description": "One result, the same record a normal run saves to its dataset.",
        "properties": {
          "packageName": {
            "type": "string"
          },
          "appId": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "sourceUrl": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "developer": {
            "type": "string"
          },
          "developerUrl": {
            "type": "string"
          },
          "rating": {
            "type": "number"
          },
          "score": {
            "type": "number"
          },
          "scoreText": {
            "type": "string"
          },
          "icon": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "free": {
            "type": "boolean"
          },
          "searchQuery": {
            "type": "string"
          },
          "rank": {
            "type": "integer"
          },
          "isExactMatch": {
            "type": "boolean"
          },
          "recordType": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "scrapedAt": {
            "type": "string"
          }
        },
        "example": {
          "packageName": "com.sec.android.app.popupcalculator",
          "appId": "com.sec.android.app.popupcalculator",
          "id": "com.sec.android.app.popupcalculator",
          "name": "Samsung Calculator",
          "title": "Samsung Calculator",
          "url": "https://play.google.com/store/apps/details?id=com.sec.android.app.popupcalculator",
          "sourceUrl": "https://play.google.com/store/apps/details?id=com.sec.android.app.popupcalculator",
          "summary": "[Key features]\nPerform four fundamental operations and engineering calculations.\n\nTo start the engineering calculator, tap the engineering calculator icon.\n\n...",
          "developer": "Samsung Electronics Co.,  Ltd.",
          "developerUrl": "https://play.google.com/store/apps/developer?id=Samsung+Electronics+Co.%2C++Ltd.",
          "rating": 4.45,
          "score": 4.45,
          "scoreText": "4.5",
          "icon": "https://play-lh.googleusercontent.com/p8rUJZjn-oJQPhrNASuJEZu3njkIxXP6P_AdeSUrXl5BrrtZDBu_YUBxJp0_WgcsaQ5HnB5-j9Fa7whGc0vo6w",
          "price": 0,
          "currency": "USD",
          "free": true,
          "searchQuery": "calculator",
          "rank": 1,
          "isExactMatch": false,
          "recordType": "app",
          "language": "en",
          "country": "us",
          "scrapedAt": "2026-11-10T15:33:11.818504+00:00"
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "errorDescription"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_input",
              "request_failed",
              "internal_error",
              "timeout",
              "busy",
              "not_found",
              "method_not_allowed",
              "payload_too_large"
            ]
          },
          "errorDescription": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "apifyToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your Apify API token (Apify Console, Settings, API and integrations)."
      }
    }
  },
  "servers": [
    {
      "url": "https://vcknmnj5f5o6x56ho.apify.actor"
    }
  ],
  "security": [
    {
      "apifyToken": []
    }
  ]
}