> ## 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. # App Store search > Canonical ranked App Store app wrappers with developer/category enrichment. Depth defaults to 100, rounds up by 100 and caps at 300. Duplicate IDs retain the first rank and are explicitly counted. Detail-only fields are null. Country accepts a documented ISO code, full name or numeric location code; language selects the DataForSEO task locale. Public Apple lookups enrich missing metadata; their category labels are not guaranteed to match the requested language. Mixed-source age advisories remain separate. Nonempty uncached responses cost five credits. Empty search, failures, cache and replay are free. Task submissions are durable and capped at twenty within the existing trial; polling may return free UPSTREAM_TASK_PENDING with the same task reused on retry. This finite trial is not sustained production capacity. `query` is sent to the ranked App Store search source. `depth` defaults to 100, rounds upward in hundreds and caps at 300. A depth of 101 requests 200. Returned results may be fewer. Duplicate IDs keep their first ranking, with `source_items` and `deduplicated` explaining the difference. `source_results` is the provider's reported match count, not a promise that all those rows were collected. Every item uses `{ app }` with title, icon, developer, category, rating, price and storefront URL. Descriptions, screenshots, related apps and other detail-only leaves are null here. Fetch app-info for those fields. `total` counts returned unique apps; no continuation cursor is provided. Choose one of the source's 105 country locations by ISO code, country name or numeric code (`US`, `United Kingdom`, `2840`). `UK` aliases `GB`. Language uses one of the 39 supported source locale codes and defaults to `en`; unsupported countries/languages fail before submitting tasks. DataForSEO supplies ranking and localized listing text. Anonymous Apple batch lookups provide developer/category metadata and missing detail fields. Those enrichment labels are not guaranteed to match the requested language. Age advisories can differ between the two sources: the source page advisory stays in `advisories` and Apple's rating is retained under `ext.appdata.apple_advisory`. The adapter does not hide that disagreement or infer a rating. Nonempty uncached results cost **5 credits** regardless of depth. Empty search results, all failures, cache hits and successful replays are free. Use `X-Max-Credits: 5`. A failed enrichment batch rejects the collection instead of charging for incomplete app rows. Use a 60-second client timeout. When task processing exceeds the polling window, an uncharged `UPSTREAM_TASK_PENDING` response asks you to retry the same parameters; durable task state avoids a new provider submission for one hour. New source tasks share a non-resetting ceiling of twenty submissions within the existing DataForSEO trial balance. No paid plan or top-up is enabled. Ongoing funded capacity remains unconfigured. ## OpenAPI ````yaml GET /app_store/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: /app_store/app-search: get: tags: - App Store summary: App Store App Search description: >- Canonical ranked App Store app wrappers with developer/category enrichment. Depth defaults to 100, rounds up by 100 and caps at 300. Duplicate IDs retain the first rank and are explicitly counted. Detail-only fields are null. Country accepts a documented ISO code, full name or numeric location code; language selects the DataForSEO task locale. Public Apple lookups enrich missing metadata; their category labels are not guaranteed to match the requested language. Mixed-source age advisories remain separate. Nonempty uncached responses cost five credits. Empty search, failures, cache and replay are free. Task submissions are durable and capped at twenty within the existing trial; polling may return free UPSTREAM_TASK_PENDING with the same task reused on retry. This finite trial is not sustained production capacity. operationId: get_app_store_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 105 documented App Store source locations: ISO code, full country name or numeric location code. UK aliases GB; default US. - name: language in: query required: false schema: type: string description: >- One of the 39 source language codes. The source task uses this locale; Apple metadata enrichment labels are not guaranteed to use it. Default en. - name: depth in: query required: false example: 100 schema: type: integer description: >- Positive requested depth, default 100; rounds up by 100 and caps at 300. Results may be fewer; duplicate source IDs are counted and collapsed to their first rank. - 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 ranked App Store app wrappers with developer/category enrichment. Depth defaults to 100, rounds up by 100 and caps at 300. Duplicate IDs retain the first rank and are explicitly counted. Detail-only fields are null. Country accepts a documented ISO code, full name or numeric location code; language selects the DataForSEO task locale. Public Apple lookups enrich missing metadata; their category labels are not guaranteed to match the requested language. Mixed-source age advisories remain separate. Nonempty uncached responses cost five credits. Empty search, failures, cache and replay are free. Task submissions are durable and capped at twenty within the existing trial; polling may return free UPSTREAM_TASK_PENDING with the same task reused on retry. This finite trial is not sustained production capacity. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: type: object properties: items: type: array maxItems: 300 items: type: object properties: app: type: object properties: id: type: string description: >- Store app ID (Google Play package name / App Store numeric id) store: type: string description: >- App marketplace ("google_play" or "app_store") 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: - string - 'null' description: String at app.developer.website 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: - string - 'null' description: String at app.category categories: type: - array - 'null' description: Array at app.categories items: type: string description: String at app.categories 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 enrichment_source: const: apple_itunes source_rank: type: - integer - 'null' minimum: 0 apple_advisory: type: - string - 'null' coverage_note: type: string required: - country - requested_language - source - enrichment_source - source_rank - apple_advisory - 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: - 100 - 200 - 300 country: type: string language: type: string source_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_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.