SocialCrawl App Store API

openapi: 3.2.0
info:
  title: SocialCrawl App Store API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: app_store
  description: App_store endpoints
paths:
  /app_store/app-search:
    get:
      summary: Search Apple App Store apps by keyword
      description: 'Returns a unified AppList of Apple App Store apps matching a keyword: title, icon, rating, price/is_free, and store URL on every item, on the same canonical `App` shape used across every app marketplace (`app.store` = "app_store"). Detail-only fields (description, screenshots, developer) are null on search items; fetch /v1/app_store/app-info for the full record. Sourced from DataForSEO''s task-based App Data API (first calls ~7-15s, then cached).'
      tags:
      - app_store
      operationId: get_app_store_app_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: query
        in: query
        required: true
        description: Search keyword (e.g. 'photo editor').
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: Storefront country as an ISO code ('US'), a full name ('United States'), or a numeric location code ('2840'). Defaults to the US.
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: Language code (e.g. 'en'). Defaults to 'en'.
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: Number of results to retrieve (default 100, rounded up to multiples of 100, max 300).
        schema:
          type: integer
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical app wrappers ({ app })
                        items:
                          type: object
                          description: Canonical app wrapper
                          properties:
                            app:
                              type: object
                              description: Canonical App object (unified across app marketplaces)
                              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
                                icon:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at app.icon
                                description:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at app.description
                                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:
                                      - string
                                      - 'null'
                                      description: String at app.developer.email
                                    address:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at app.developer.address
                                    website:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at app.developer.website
                                rating:
                                  type: object
                                  description: Aggregate rating (value, max, number of ratings)
                                  properties:
                                    value:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at app.rating.value
                                    max:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at app.rating.max
                                    count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at app.rating.count
                                price:
                                  type: object
                                  description: Price block (current, original, currency, is_free, displayed)
                                  properties:
                                    current:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at app.price.current
                                    original:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at app.price.original
                                    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:
                                  - object
                                  - 'null'
                                  description: 'Install signal (Google only): { display "1,000,000,000+", count }; null on Apple'
                                  properties:
                                    display:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at app.installs.display
                                    count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at app.installs.count
                                version:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at app.version
                                minimum_os_version:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at app.minimum_os_version
                                size:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at app.size
                                released_at:
                                  type:
                                  - string
                                  - integer
                                  - 'null'
                                  description: 'Union: string | integer | null'
                                updated_at:
                                  type:
                                  - string
                                  - integer
                                  - 'null'
                                  description: 'Union: string | integer | null'
                                update_notes:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at app.update_notes
                                image_urls:
                                  type:
                                  - array
                                  - 'null'
                                  description: Screenshot URLs
                                  items:
                                    type: string
                                    description: Screenshot URLs
                                video_urls:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at app.video_urls
                                  items:
                                    type: string
                                    description: String at app.video_urls
                                languages:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at app.languages
                                  items:
                                    type: string
                                    description: String at app.languages
                                advisories:
                                  type:
                                  - array
                                  - 'null'
                                  description: Apple age/content advisories (null on Google)
                                  items:
                                    type: string
                                    description: Apple age/content advisories (null on Google)
                                genres:
                                  type:
                                  - array
                                  - 'null'
                                  description: Google Play genres (null on Apple)
                                  items:
                                    type: string
                                    description: Google Play genres (null on Apple)
                                tags:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at app.tags
                                  items:
                                    type: string
                                    description: String at app.tags
                                similar_apps:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at app.similar_apps
                                  items:
                                    type: object
                                    description: 'Nested object: app.similar_apps'
                                    properties:
                                      id:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at app.similar_apps.id
                                      title:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at app.similar_apps.title
                                      url:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at app.similar_apps.url
                                more_by_developer:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at app.more_by_developer
                                  items:
                                    type: object
                                    description: 'Nested object: app.more_by_developer'
                                    properties:
                                      id:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at app.more_by_developer.id
                                      title:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at app.more_by_developer.title
                                      url:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at app.more_by_developer.url
                                ext:
                                  type:
                                  - object
                                  - 'null'
                                  description: 'Nested object: app.ext'
                                  properties:
                                    appdata:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at app.ext.appdata
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.
                      total:
                        type:
                        - integer
                        - 'null'
                        description: Total number of matching results, when the upstream provides a count. Omitted otherwise.
                      dropped:
                        type: integer
                        description: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                    required:
                    - dropped
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                  pagination:
                    type: object
                    description: Cursor state for this page. Present on every list response.
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.
                      has_more:
                        type: boolean
                        description: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.
                      page_size:
                        type: integer
                        description: Number of items in THIS page.
                    required:
                    - next_cursor
                    - has_more
                    - page_size
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
                - pagination
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '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'
  /app_store/search-suggestions:
    get:
      summary: Get Apple App Store search suggestions
      description: 'Returns Apple''s App Store search autocomplete (''search hints'') for a keyword stem: the same suggestions the store''s search box surfaces, ranked by Apple''s own priority. The day Apple starts autocompleting a phrase, real demand exists; poll a stem daily and diff to catch rising app keywords early. Each item is `{ term, priority }` where `priority` is the 1-based upstream rank (Apple exposes no numeric score). Returns a list under `items`.'
      tags:
      - app_store
      operationId: get_app_store_search_suggestions
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: query
        in: query
        required: true
        description: Partial search keyword to autocomplete (e.g. 'reverse').
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2 storefront country code. Defaults to 'us'.
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of search result objects
                        items:
                          type: object
                          description: Search result item
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.
                      total:
                        type:
                        - integer
                        - 'null'
                        description: Total number of matching results, when the upstream provides a count. Omitted otherwise.
                      dropped:
                        type: integer
                        description: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                    required:
                    - dropped
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                  pagination:
                    type: object
                    description: Cursor state for this page. Present on every list response.
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.
                      has_more:
                        type: boolean
                        description: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.
                      page_size:
                        type: integer
                        description: Number of items in THIS page.
                    required:
                    - next_cursor
                    - has_more
                    - page_size
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
                - pagination
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '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'
  /app_store/app-info:
    get:
      summary: Get full Apple App Store app details
      description: 'Returns the full canonical `App` record for one Apple App Store app keyed by its numeric `app_id`: title, description, developer, rating, price, version, minimum iOS version, size, screenshots, supported languages, age advisories, similar apps, and update date. The `app.store` field is always "app_store"; Google-only leaves (installs, genres, developer email/address) are null, and `released_at` is null (Apple deprecates it). Get the `app_id` from /v1/app_store/app-search. Sourced from DataForSEO''s task-based App Data API.'
      tags:
      - app_store
      operationId: get_app_store_app_info
      security:
      - ApiKeyAuth: []
      x-credit-tier: adva

# --- truncated at 32 KB (141 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-app-store-api-openapi.yml