> ## Documentation Index > Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Google Play search > Canonical Google Play search rows wrapped as {app}. Requested depth defaults to 30, rounds up by 30, and caps at 200 (source maximum, lower than the reference 300). Google Play often supplies only 30 ranked rows. Detail-only fields are null. Country accepts one of 211 source country codes, full names or numeric location codes; language accepts 127 source codes. Nonempty fresh responses cost five credits. Empty search, failures, cache and replay cost zero. New tasks share a finite persistent trial allowance; pending tasks are reused on retry for one hour. Only US/GB English were live-tested. Send a `query` to retrieve ranked app listings. Every item is `{ app }` on the shared App shape, with package ID, title, icon, developer, ratings, price and store URL. Detail-only fields are null; use app-info for those. `depth` defaults to 30, rounds upward by 30, and caps at **200**, the source maximum. This differs from the reference's 300. Google Play commonly exposes only 30 ranked rows; a live depth=200 check returned 30. `requested_depth` and `effective_depth` disclose the request and clamp. No continuation cursor is available. Duplicate IDs retain their first source rank; `source_items` and `deduplicated` preserve the difference. `total` is the returned unique count. `source_reported_results` may be zero for a nonempty page and is not a global result count. Country accepts one of 211 DataForSEO country locations by ISO code, country name or numeric location code (`US`, `United Kingdom`, `2840`). `UK` aliases `GB`. Language accepts one of 127 source locale codes and defaults to `en`. US and GB English are the live acceptance fixtures; other configured locales are not individually certified. Unsupported inputs fail before task submission. Nonempty uncached responses cost **5 credits**. Empty search results, errors, cache and replay are free. Use `X-Max-Credits: 5` and allow a 60-second client timeout. A task that remains pending returns an uncharged `UPSTREAM_TASK_PENDING`; retrying the same parameters reuses durable task state for one hour instead of submitting another task. The existing DataForSEO key and free balance are reused. New Google Play tasks share a non-resetting 140-unit verification ceiling: one unit per detail or per 30 requested search rows (at most seven for a search). Missing or exhausted budget state fails closed. No top-up or paid plan is enabled; sustained capacity remains unconfigured. ## OpenAPI ````yaml GET /google_play/app-search openapi: 3.1.0 info: title: SocialQuery API version: '2026-10-09' description: >- Documented requests for public-source records. Inspect accepted inputs and credit amounts, then verify the selected operation before integrating preview coverage. servers: - url: https://socialquery.dev/v1 security: - apiKey: [] paths: /google_play/app-search: get: tags: - Google Play summary: Google Play App Search description: >- Canonical Google Play search rows wrapped as {app}. Requested depth defaults to 30, rounds up by 30, and caps at 200 (source maximum, lower than the reference 300). Google Play often supplies only 30 ranked rows. Detail-only fields are null. Country accepts one of 211 source country codes, full names or numeric location codes; language accepts 127 source codes. Nonempty fresh responses cost five credits. Empty search, failures, cache and replay cost zero. New tasks share a finite persistent trial allowance; pending tasks are reused on retry for one hour. Only US/GB English were live-tested. operationId: get_google_play_app_search parameters: - name: query in: query required: true example: photo editor schema: type: string - name: country in: query required: false example: United States schema: type: string description: >- One of 211 source countries by ISO code, full country name or numeric location code. UK aliases GB. Default US; only US and GB live-tested. - name: language in: query required: false schema: type: string description: >- One of 127 source language codes. Default en; only English live-tested. - name: depth in: query required: false example: 30 schema: type: integer description: >- Positive requested depth, default 30; rounds upward by 30 and caps at 200, the documented source maximum. Organic keyword search usually returns only about 30 rows. No continuation cursor. - name: Cache-Control in: header required: false example: no-cache schema: type: string - name: Idempotency-Key in: header required: false example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c schema: type: string - name: X-Max-Credits in: header required: false description: >- Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero. schema: type: integer minimum: 0 responses: '200': description: >- Canonical Google Play search rows wrapped as {app}. Requested depth defaults to 30, rounds up by 30, and caps at 200 (source maximum, lower than the reference 300). Google Play often supplies only 30 ranked rows. Detail-only fields are null. Country accepts one of 211 source country codes, full names or numeric location codes; language accepts 127 source codes. Nonempty fresh responses cost five credits. Empty search, failures, cache and replay cost zero. New tasks share a finite persistent trial allowance; pending tasks are reused on retry for one hour. Only US/GB English were live-tested. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: type: object properties: items: type: array maxItems: 200 items: type: object properties: app: type: object properties: id: type: string description: >- Store app ID (Google Play package name / App Store numeric id) store: const: google_play url: type: - string - 'null' description: String at app.url title: type: - string - 'null' description: App title subtitle: type: 'null' icon: type: - string - 'null' description: String at app.icon description: type: 'null' developer: type: object description: >- Developer block (name, id, url; email/address for Google) properties: id: type: - string - 'null' description: String at app.developer.id name: type: - string - 'null' description: String at app.developer.name url: type: - string - 'null' description: String at app.developer.url email: type: 'null' address: type: 'null' website: type: 'null' rating: type: object description: >- Aggregate rating (value, max, number of ratings) properties: value: type: - number - 'null' minimum: 0 maximum: 5 max: type: - number - 'null' enum: - 5 - null count: type: - integer - 'null' minimum: 0 price: type: object description: >- Price block (current, original, currency, is_free, displayed) properties: current: type: - number - 'null' minimum: 0 original: type: - number - 'null' minimum: 0 currency: type: - string - 'null' description: String at app.price.currency is_free: type: - boolean - 'null' description: Boolean at app.price.is_free displayed: type: - string - 'null' description: String at app.price.displayed reviews_count: type: - integer - 'null' description: Numeric at app.reviews_count category: type: 'null' categories: type: 'null' installs: type: 'null' version: type: 'null' minimum_os_version: type: 'null' size: type: 'null' released_at: type: 'null' updated_at: type: 'null' update_notes: type: 'null' image_urls: type: 'null' video_urls: type: 'null' languages: type: 'null' advisories: type: 'null' genres: type: 'null' tags: type: 'null' similar_apps: type: 'null' more_by_developer: type: 'null' ext: type: object properties: appdata: type: object properties: country: type: string requested_language: type: string source: const: dataforseo source_rank: type: - integer - 'null' minimum: 0 coverage_note: type: string required: - country - requested_language - source - source_rank - coverage_note additionalProperties: false required: - appdata additionalProperties: false required: - id - store - url - title - subtitle - icon - description - developer - rating - price - reviews_count - category - categories - installs - version - minimum_os_version - size - released_at - updated_at - update_notes - image_urls - video_urls - languages - advisories - genres - tags - similar_apps - more_by_developer - ext additionalProperties: false required: - app additionalProperties: false total: type: integer minimum: 0 returned_count: type: integer minimum: 0 next_cursor: type: 'null' requested_depth: type: integer minimum: 1 effective_depth: type: integer enum: - 30 - 60 - 90 - 120 - 150 - 180 - 200 country: type: string language: type: string source_reported_results: type: - integer - 'null' minimum: 0 source_items: type: integer minimum: 0 deduplicated: type: integer minimum: 0 collected_at: type: - string - 'null' coverage_note: type: string required: - items - total - returned_count - next_cursor - requested_depth - effective_depth - country - language - source_reported_results - source_items - deduplicated - collected_at - coverage_note additionalProperties: false required: - data '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '405': $ref: '#/components/responses/Error405' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' '503': $ref: '#/components/responses/Error503' '504': $ref: '#/components/responses/Error504' components: schemas: SocialQueryResponse: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - data properties: success: type: boolean const: true platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean data: type: object additionalProperties: true description: >- The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null. SocialQueryError: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - error properties: success: type: boolean const: false platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean error: type: object required: - code - type - message - status - doc_url properties: code: type: string type: type: string message: type: string status: type: integer doc_url: type: string format: uri responses: Error400: description: Upstream rejected the request. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error401: description: Missing, expired, invalid, or revoked API key. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error402: description: Insufficient SocialQuery credits. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error403: description: Key scope or provider policy denied access. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error404: description: Endpoint or upstream resource not found. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error405: description: HTTP method is not supported. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error409: description: Idempotency conflict or request in progress. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error422: description: Invalid parameters. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error429: description: Request limit reached. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error500: description: Request processing failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error502: description: Upstream service failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error503: description: Provider or required service is unavailable. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error504: description: Upstream service timed out. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.