openapi: 3.0.0
info:
  title: Apple App Store Top Charts API
  description: |
    Apple App Store Top Charts API allows you to retrieve top-ranked applications and games on the Apple App Store. You can filter by device type (iPhone or iPad), country, category, and chart type (free or paid).

    **Cross-linking**: The `id` returned in each product within `top_charts` can be used with the Apple Product API to fetch comprehensive information about a specific app. Pass it as the `app_id` parameter to the Apple Product API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Apple App Store Top Charts Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["apple_app_store_top_charts"]
        - name: chart
          in: query
          required: false
          description: 'Type of chart to retrieve. Available options: top_free (default) or top_paid'
          schema:
            type: string
            enum: ["top_free", "top_paid"]
            default: "top_free"
        - name: store_device
          in: query
          required: false
          description: 'Device type for the App Store. Available options: iphone (default) or ipad'
          schema:
            type: string
            enum: ["iphone", "ipad"]
            default: "iphone"
        - name: category
          in: query
          required: false
          description: 'App category to filter results. Default: all'
          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", "kids_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", "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"
        - name: country
          in: query
          required: false
          description: 'Two-letter country code (e.g., us, gb, de, jp). Default: us'
          schema:
            type: string
            default: "us"
      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'
        top_charts:
          type: array
          description: List of top-ranked apps in the specified category and chart
          items:
            $ref: '#/components/schemas/TopChartProduct'
        error:
          type: string
          description: Error message if the search failed
    SearchMetadata:
      type: object
      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
          description: 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: The search engine used
        chart:
          type: string
          description: Chart type (top_free or top_paid)
        country:
          type: string
          description: Country code
        store_device:
          type: string
          description: Device type (iphone or ipad)
        category:
          type: string
          description: App category
    TopChartProduct:
      type: object
      properties:
        position:
          type: integer
          description: Position of the app in the top charts (1-based ranking)
        id:
          type: string
          description: Unique identifier for the app on the App Store
        title:
          type: string
          description: Name of the app
        description:
          type: string
          description: Brief description or tagline of the app
        link:
          type: string
          description: Direct link to the app on the App Store
        thumbnail:
          type: string
          description: URL to the app's thumbnail/icon image
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong