openapi: 3.0.0
info:
  title: Apple App Store API
  description: |
    Search for apps in the Apple App Store. This API allows you to find apps by name, filter by language and country, and retrieve detailed information about each application including ratings, reviews, pricing, and screenshots.

    **Related API**: Use the `id` field returned in app results to fetch additional app details.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Apple App Store Search
      description: Search for apps in the Apple App Store
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["apple_app_store"]
            default: "apple_app_store"
        - name: term
          in: query
          required: true
          description: The search term or app name to find
          schema:
            type: string
        - name: country
          in: query
          required: false
          description: 'Two-letter country code (ISO 3166-1 alpha-2). Default: "us"'
          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", "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: lang
          in: query
          required: false
          description: 'Language and locale code (e.g., "en-us", "fr-fr"). Default: "en-us"'
          schema:
            type: string
            enum: ["pt-br", "it-it", "hi-in", "ca-es", "es-es", "zh-tw", "th-th", "da-dk", "fi-fi", "en-gb", "nl-nl", "pl-pl", "ro-ro", "zh-cn", "no-no", "pt-pt", "de-ch", "uk-ua", "en-us", "vi-vi", "sv-se", "en-ca", "fr-fr", "sk-sk", "zh-hk", "hr-hr", "en-au", "ko-kr", "tr-tr", "el-gr", "ms-my", "id-id", "cs-cz", "hu-hu", "fr-ca", "es-mx", "de-de", "ru-ru", "ja-jp"]
            default: "en-us"
        - name: num
          in: query
          required: false
          description: 'Number of results to return (1-200). Default: 10'
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 10
        - name: include_explicit
          in: query
          required: false
          description: 'Include apps with explicit content ("true" or "false"). Default: "true"'
          schema:
            type: string
            enum: ["true", "false"]
            default: "true"
        - name: device
          in: query
          required: false
          description: 'Device type to filter results: "mobile" for iPhone, "tablet" for iPad, "desktop" for Mac. Default: "mobile"'
          schema:
            type: string
            enum: ["mobile", "tablet", "desktop"]
            default: "mobile"
        - name: property
          in: query
          required: false
          description: 'Filter by app property. Only "developer" is supported, which filters results by developer name.'
          schema:
            type: string
            enum: ["developer"]
      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'
        organic_results:
          type: array
          description: List of apps matching the search query
          items:
            $ref: '#/components/schemas/OrganicResult'
        error:
          type: string
          description: Error message if the search returned no results
    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: Search engine used
        term:
          type: string
          description: Search term used
        country:
          type: string
          description: Country filter applied
        lang:
          type: string
          description: Language filter applied
        num:
          type: integer
          description: Number of results returned
        include_explicit:
          type: string
          description: Whether explicit content is included
        device:
          type: string
          description: Device type filter applied
        property:
          type: string
          description: Property filter applied
    OrganicResult:
      type: object
      
      properties:
        position:
          type: integer
          description: Position of the result in the search results
        id:
          type: integer
          description: Unique identifier for the app (trackId)
        title:
          type: string
          description: Name of the app
        bundle_id:
          type: string
          description: Bundle identifier for the app
        version:
          type: string
          description: Current version of the app
        has_vpp_license:
          type: boolean
          description: Whether the app has VPP (Volume Purchase Program) device-based licensing enabled
        age_rating:
          type: string
          description: Age rating/content advisory rating for the app
        minimum_os_version:
          type: string
          description: Minimum iOS/macOS/tvOS version required to run the app
        description:
          type: string
          description: Full description of the app
        link:
          type: string
          description: Direct link to the app on the App Store
        release_date:
          type: string
          description: Date when the app was first released
        latest_version_release_date:
          type: string
          description: Release date of the current version
        price:
          $ref: '#/components/schemas/Price'
        rating:
          type: number
          format: float
          description: Average user rating (0-5)
        reviews:
          type: integer
          description: Total number of user reviews
        genres:
          type: array
          items:
            $ref: '#/components/schemas/Genre'
          description: Categories/genres the app belongs to
        developer:
          $ref: '#/components/schemas/Developer'
        size_in_bytes:
          type: integer
          description: Size of the app in bytes
        supported_languages:
          type: array
          items:
            type: string
          description: ISO 639-1 language codes supported by the app
        features:
          type: array
          items:
            type: string
          description: List of app features
        advisories:
          type: array
          items:
            type: string
          description: Content advisories for the app
        is_game_center_enabled:
          type: boolean
          description: Whether the app has Game Center support
        seller_link:
          type: string
          description: Link to the developer's seller page
        release_note:
          type: string
          description: Release notes for the current version
        logos:
          type: array
          items:
            $ref: '#/components/schemas/Logo'
          description: App icon/logo images at various sizes
        screenshots:
          $ref: '#/components/schemas/Screenshots'
        supported_devices:
          type: array
          items:
            type: string
          description: List of supported device types
    Price:
      type: object
      
      properties:
        is_free:
          type: boolean
          description: Whether the app is free
        type:
          type: string
          description: 'Pricing type: "Free", "Paid", or "Free Trial"'
        formatted_price:
          type: string
          description: 'Formatted price string (e.g., "$0.00", "$9.99")'
        extracted_price:
          type: number
          format: float
          description: Numeric price value
        currency:
          type: string
          description: 'Currency code (e.g., "USD", "EUR")'
        currency_symbol:
          type: string
          description: 'Currency symbol (e.g., "$", "€")'
    Genre:
      type: object
      properties:
        name:
          type: string
          description: Name of the genre/category
        id:
          type: integer
          description: Unique identifier for the genre
        is_primary:
          type: boolean
          description: Whether this is the primary genre for the app
    Developer:
      type: object
      properties:
        name:
          type: string
          description: Name of the app developer/artist
        id:
          type: integer
          description: Unique identifier for the developer
        link:
          type: string
          description: Direct link to the developer's profile on the App Store
    Logo:
      type: object
      properties:
        link:
          type: string
          description: URL to the app icon/logo image
        width:
          type: integer
          description: Width of the image in pixels
        height:
          type: integer
          description: Height of the image in pixels
    Screenshot:
      type: object
      properties:
        link:
          type: string
          description: URL to the screenshot image
        width:
          type: integer
          description: Width of the image in pixels
        height:
          type: integer
          description: Height of the image in pixels
    Screenshots:
      type: object
      properties:
        general:
          type: array
          items:
            $ref: '#/components/schemas/Screenshot'
          description: Screenshots for iPhone/general device
        ipad:
          type: array
          items:
            $ref: '#/components/schemas/Screenshot'
          description: Screenshots for iPad
        apple_tv:
          type: array
          items:
            $ref: '#/components/schemas/Screenshot'
          description: Screenshots for Apple TV
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong