openapi: 3.0.0
info:
  title: Apple App Store Top Grossing Apps API
  description: |
    Apple App Store Top Grossing Apps API returns ranked top-grossing apps for a selected country and category.

    **Cross-linking**: The `id` returned for each app can be passed as the `product_id` parameter to the Apple Product API for detailed app information.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Apple App Store Top Grossing Apps Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["apple_app_store_top_grossing"]
        - name: country
          in: query
          required: false
          description: App Store storefront country
          schema:
            type: string
            enum: ["al", "dz", "ao", "ai", "ag", "ar", "am", "au", "at", "az", "bs", "bh", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "bw", "br", "vg", "bn", "bg", "bf", "kh", "ca", "cv", "ky", "cl", "td", "cn", "co", "cd", "cr", "hr", "cy", "cz", "dk", "dm", "do", "ec", "eg", "sv", "ee", "fj", "fi", "fr", "de", "gm", "gb", "gh", "gr", "gd", "gt", "gw", "gy", "hn", "hk", "hu", "is", "in", "id", "ie", "il", "it", "jm", "jp", "jo", "kz", "ke", "kw", "kg", "la", "lv", "lb", "lr", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "ml", "mt", "mr", "mu", "mx", "fm", "md", "mn", "ms", "mz", "na", "np", "nl", "nz", "ni", "ne", "ng", "no", "om", "pk", "pw", "pa", "pg", "py", "pe", "ph", "pl", "pt", "qa", "ro", "ru", "st", "sa", "sn", "sc", "sl", "sg", "sk", "si", "sb", "za", "kr", "es", "lk", "kn", "lc", "vc", "sr", "sz", "se", "ch", "tw", "tj", "tz", "th", "tt", "tn", "tr", "tm", "tc", "ug", "ua", "ae", "us", "uy", "uz", "ve", "vn", "ye", "zw"]
            default: "us"
        - name: num
          in: query
          required: false
          description: Number of apps to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: store_device
          in: query
          required: false
          description: 'Device chart to rank. Available options: iphone (default), ipad or appletv'
          schema:
            type: string
            enum: ["iphone", "ipad", "appletv"]
            default: "iphone"
        - name: category
          in: query
          required: false
          description: App Store category used to filter rankings
          schema:
            type: string
            enum: ["all", "books_apps", "business_apps", "developer_tools_apps", "education_apps", "entertainment_apps", "finance_apps", "food_drink_apps", "graphics_design_apps", "health_fitness_apps", "lifestyle_apps", "magazines_newspapers_apps", "medical_apps", "music_apps", "navigation_apps", "news_apps", "photo_video_apps", "productivity_apps", "reference_apps", "shopping_apps", "social_networking_apps", "sports_apps", "travel_apps", "utilities_apps", "weather_apps", "games", "action_games", "adventure_games", "board_games", "card_games", "casino_games", "casual_games", "family_games", "music_games", "puzzle_games", "racing_games", "role_playing_games", "simulation_games", "sports_games", "strategy_games", "trivia_games", "word_games"]
            default: "all"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        chart_information:
          $ref: '#/components/schemas/ChartInformation'
        top_grossing_apps:
          type: array
          description: Ranked top-grossing apps
          items:
            $ref: '#/components/schemas/TopGrossingApp'
        error:
          type: string
          description: Error message when no results are returned
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          nullable: true
          description: Public Apple App Store URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        country:
          type: string
          description: App Store storefront country
        store_device:
          type: string
          description: Device chart that was ranked (iphone, ipad or appletv)
        num:
          type: integer
          description: Number of requested apps
        category:
          type: string
          description: App Store category filter
    ChartInformation:
      type: object
      properties:
        title:
          type: string
          description: Feed title as published by Apple
        link:
          type: string
          description: Apple's public chart page for this storefront and category
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the chart snapshot Apple served
    TopGrossingApp:
      type: object
      properties:
        position:
          type: integer
          description: Ranking position
        id:
          type: string
          description: App Store app identifier
        bundle_id:
          type: string
          description: App bundle identifier
        title:
          type: string
          description: App name
        description:
          type: string
          description: App description
        link:
          type: string
          description: App Store app URL
        thumbnail:
          type: string
          description: App icon URL at the largest size Apple publishes in the feed
        logos:
          type: array
          description: App icon in every size Apple publishes, plus a higher-resolution variant derived from Apple's image CDN
          items:
            $ref: '#/components/schemas/Logo'
        developer:
          $ref: '#/components/schemas/Developer'
        category:
          $ref: '#/components/schemas/Category'
        price:
          $ref: '#/components/schemas/Price'
        release_date:
          type: string
          format: date-time
          description: Initial app release timestamp
        release_date_text:
          type: string
          description: Initial app release date formatted for the storefront locale
    Logo:
      type: object
      properties:
        link:
          type: string
          description: App icon URL
        width:
          type: integer
          description: Icon width in pixels. Equal to the height for App Store icons; Apple TV apps ship wider 5:3 artwork
        height:
          type: integer
          description: Icon height in pixels
    Developer:
      type: object
      properties:
        name:
          type: string
          description: Developer name
        id:
          type: string
          description: App Store developer identifier
        link:
          type: string
          description: Developer App Store URL
    Category:
      type: object
      properties:
        id:
          type: integer
          description: App Store category identifier
        name:
          type: string
          description: Localized App Store category name
        canonical_name:
          type: string
          description: Canonical English App Store category name
        link:
          type: string
          description: App Store genre URL for this category
    Price:
      type: object
      properties:
        type:
          type: string
          enum: ["Free", "Paid"]
          description: App pricing type
        formatted_price:
          type: string
          description: Price label shown by the App Store
        extracted_price:
          type: number
          format: float
          description: Numeric app price
        currency:
          type: string
          description: ISO 4217 currency code
        currency_symbol:
          type: string
          description: Currency symbol
        is_free:
          type: boolean
          description: Present and true when the app can be downloaded for free; omitted for paid apps
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong