> ## 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 suggestions

> Return native App Store autocomplete suggestions for a keyword stem and country. Each item contains term and priority, the one-based source rank; no popularity score or search-volume estimate is invented. query accepts 1–200 characters. country defaults to us and is case-insensitive; use gb, not uk. Unsupported storefronts return a free 400 before a source call. A nonempty fresh response costs one credit; validated empty results, errors, cache hits and idempotent replays are free. Exact requests cache for five minutes. No pagination.

Get native App Store **autocomplete suggestions** for a partial keyword. Each `items` entry contains `{ term, priority }`: the suggested phrase and its one-based position in Apple's response. This endpoint returns suggestions, not app search records. Rank is not a search-volume or popularity score.

`query` is required and accepts 1–200 characters without control characters; surrounding whitespace is removed. `country` defaults to `us`, is case-insensitive, and selects the requested Apple storefront. Use **`gb`, not `uk`**, for the United Kingdom. Unsupported countries return a free **400 `UNSUPPORTED_COUNTRY`** before contacting Apple. Unsupported options such as `cursor` or `limit` return 422.

The country map matches the 175 codes in [Apple's App Store region picker](https://apps.apple.com/us/iphone/today), captured October 12, 2026. Apple's public storefront directory supplied 174 numeric mappings; the mainland China mapping was checked separately with a live Chinese-language response. This dated mapping is not a guarantee that every country is available continuously. Apple's hints response does not echo its country.

A fresh nonempty response costs **1 credit**. A validated empty suggestion list, errors, cache hits and successful idempotent replays cost zero. Use `X-Max-Credits: 1` to cap the charge. Exact requests cache for five minutes; `Cache-Control: no-cache` requests fresh suggestions.

`total` and `returned_count` count the returned suggestions, `dropped` is zero and `next_cursor` is null. Malformed or failed upstream responses remain errors; they are never reported as an empty successful list. Suggestions represent the current store response, not historical keyword demand.


## OpenAPI

````yaml GET /app_store/search-suggestions
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/search-suggestions:
    get:
      tags:
        - App Store
      summary: App Store Search Suggestions
      description: >-
        Return native App Store autocomplete suggestions for a keyword stem and
        country. Each item contains term and priority, the one-based source
        rank; no popularity score or search-volume estimate is invented. query
        accepts 1–200 characters. country defaults to us and is
        case-insensitive; use gb, not uk. Unsupported storefronts return a free
        400 before a source call. A nonempty fresh response costs one credit;
        validated empty results, errors, cache hits and idempotent replays are
        free. Exact requests cache for five minutes. No pagination.
      operationId: get_app_store_search_suggestions
      parameters:
        - name: query
          in: query
          required: true
          example: reverse
          schema:
            type: string
            minLength: 1
            maxLength: 200
          description: >-
            Partial search keyword to autocomplete, without control characters.
            Surrounding whitespace is removed.
        - name: country
          in: query
          required: false
          example: us
          schema:
            type: string
            default: us
          description: >-
            Case-insensitive App Store country code, default us. Use gb for the
            United Kingdom; uk and unsupported codes return free 400. Country
            mappings match the 175 codes in the Apple region picker captured
            October 12, 2026.
        - 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: >-
            Return native App Store autocomplete suggestions for a keyword stem
            and country. Each item contains term and priority, the one-based
            source rank; no popularity score or search-volume estimate is
            invented. query accepts 1–200 characters. country defaults to us and
            is case-insensitive; use gb, not uk. Unsupported storefronts return
            a free 400 before a source call. A nonempty fresh response costs one
            credit; validated empty results, errors, cache hits and idempotent
            replays are free. Exact requests cache for five minutes. No
            pagination.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            maxItems: 100
                            items:
                              type: object
                              properties:
                                term:
                                  type: string
                                priority:
                                  type: integer
                                  minimum: 1
                                  maximum: 100
                              required:
                                - term
                                - priority
                              additionalProperties: false
                          total:
                            type: integer
                            minimum: 0
                          returned_count:
                            type: integer
                            minimum: 0
                          dropped:
                            const: 0
                          next_cursor:
                            type: 'null'
                          query:
                            type: string
                          country:
                            type: string
                          source_url:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - total
                          - returned_count
                          - dropped
                          - next_cursor
                          - query
                          - country
                          - source_url
                          - 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.