App Store App Search

curl --request GET \
  --url https://socialquery.dev/v1/app_store/app-search \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/app_store/app-search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "items": [
      {
        "app": {
          "id": "<string>",
          "store": "<string>",
          "url": "<string>",
          "title": "<string>",
          "subtitle": null,
          "icon": "<string>",
          "description": null,
          "developer": {
            "id": "<string>",
            "name": "<string>",
            "url": "<string>",
            "email": null,
            "address": null,
            "website": "<string>"
          },
          "rating": {
            "value": 2.5,
            "max": 5,
            "count": 1
          },
          "price": {
            "current": 1,
            "original": 1,
            "currency": "<string>",
            "is_free": true,
            "displayed": "<string>"
          },
          "reviews_count": 123,
          "category": "<string>",
          "categories": [
            "<string>"
          ],
          "installs": null,
          "version": null,
          "minimum_os_version": null,
          "size": null,
          "released_at": null,
          "updated_at": null,
          "update_notes": null,
          "image_urls": null,
          "video_urls": null,
          "languages": null,
          "advisories": null,
          "genres": null,
          "tags": null,
          "similar_apps": null,
          "more_by_developer": null,
          "ext": {
            "appdata": {
              "country": "<string>",
              "requested_language": "<string>",
              "source": "dataforseo",
              "enrichment_source": "apple_itunes",
              "source_rank": 1,
              "apple_advisory": "<string>",
              "coverage_note": "<string>"
            }
          }
        }
      }
    ],
    "total": 1,
    "returned_count": 1,
    "next_cursor": null,
    "requested_depth": 2,
    "effective_depth": 100,
    "country": "<string>",
    "language": "<string>",
    "source_results": 1,
    "source_items": 1,
    "deduplicated": 1,
    "collected_at": "<string>",
    "coverage_note": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

App Store

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.

GET

app_store

app-search

App Store App Search

curl --request GET \
  --url https://socialquery.dev/v1/app_store/app-search \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/app_store/app-search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "items": [
      {
        "app": {
          "id": "<string>",
          "store": "<string>",
          "url": "<string>",
          "title": "<string>",
          "subtitle": null,
          "icon": "<string>",
          "description": null,
          "developer": {
            "id": "<string>",
            "name": "<string>",
            "url": "<string>",
            "email": null,
            "address": null,
            "website": "<string>"
          },
          "rating": {
            "value": 2.5,
            "max": 5,
            "count": 1
          },
          "price": {
            "current": 1,
            "original": 1,
            "currency": "<string>",
            "is_free": true,
            "displayed": "<string>"
          },
          "reviews_count": 123,
          "category": "<string>",
          "categories": [
            "<string>"
          ],
          "installs": null,
          "version": null,
          "minimum_os_version": null,
          "size": null,
          "released_at": null,
          "updated_at": null,
          "update_notes": null,
          "image_urls": null,
          "video_urls": null,
          "languages": null,
          "advisories": null,
          "genres": null,
          "tags": null,
          "similar_apps": null,
          "more_by_developer": null,
          "ext": {
            "appdata": {
              "country": "<string>",
              "requested_language": "<string>",
              "source": "dataforseo",
              "enrichment_source": "apple_itunes",
              "source_rank": 1,
              "apple_advisory": "<string>",
              "coverage_note": "<string>"
            }
          }
        }
      }
    ],
    "total": 1,
    "returned_count": 1,
    "next_cursor": null,
    "requested_depth": 2,
    "effective_depth": 100,
    "country": "<string>",
    "language": "<string>",
    "source_results": 1,
    "source_items": 1,
    "deduplicated": 1,
    "collected_at": "<string>",
    "coverage_note": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

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.

Authorizations

x-api-key

string

header

required

Headers

Cache-Control

string

Idempotency-Key

string

X-Max-Credits

integer

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.

Required range: x >= 0

Query Parameters

query

string

required

country

string

One of 105 documented App Store source locations: ISO code, full country name or numeric location code. UK aliases GB; default US.

language

string

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.

depth

integer

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.

Response

success

boolean

required

platform

string

required

endpoint

string

required

credits_used

integer

required

Required range: x >= 0

credits_remaining

integer | null

required

request_id

string

required

cached

boolean

required

data

object

required

The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null.

Show child attributes