How to Search for visionOS Apps with IPATool and Its Limitations

IPATool supports visionOS app discovery through the --platform visionos flag by scraping Apple's public storefront HTML, though results are permanently capped at 12 apps and depend on specific parsing logic that filters by purchase configuration.

IPATool is a command-line interface for querying and downloading apps from the Apple App Store across iOS, iPadOS, tvOS, and visionOS platforms. While the tool provides a unified search command for all platforms, the visionOS implementation follows a distinct architectural path utilizing web scraping rather than standard APIs, introducing specific constraints that affect result completeness and reliability.

How IPATool Implements visionOS Search

The visionOS search functionality diverges from standard platform searches by targeting Apple's public storefront web interface instead of the iTunes Search API. This approach is necessary because visionOS app metadata is primarily exposed through rendered HTML pages rather than structured JSON endpoints.

Command Parsing and Platform Detection

In cmd/search.go, the tool defines a Cobra command that accepts the --platform flag alongside search terms and result limits. The searchCmd function processes user input and calls appstore.ParsePlatform to convert the string value into an internal Platform enum. When the platform resolves to PlatformVisionOS, the execution flow switches to a specialized handler at line 25 rather than the standard API path used for iOS and iPadOS.

The Search Execution Flow

The pkg/appstore/appstore_search.go file contains the core Search method, which constructs a SearchInput struct containing the authenticated account, search term, limit, and platform identifier. For visionOS queries, this method bypasses the standard iTunes API URL construction and instead invokes searchVisionOS at line 32, initiating a multi-step scraping process distinct from other platforms.

VisionOS-Specific Scraping Logic

The searchVisionOS function in pkg/appstore/appstore_storefront.go executes a five-stage pipeline:

1. Storefront Request: The function builds a public storefront URL via visionSearchURL (line 43), incorporating the user's country code and search term. This URL returns an HTML page listing visionOS apps for the specific storefront.

2. JSON Extraction: The serializedServerData function (lines 39-66) locates the <script id="serialized-server-data"> element within the HTML response and extracts the embedded JSON payload containing raw app metadata.

3. App Filtering: The storefrontVisionApps function traverses the decoded JSON structure, selecting only entries where $kind equals "AppSearchResult" and containsVisionPurchaseConfiguration returns true. This filtering step deduplicates entries and enforces a hard ceiling of 12 results via the maxVisionOSSearchResults constant defined at line 15.

4. Metadata Hydration: The discovered app IDs are passed to lookupIDsRequest (lines 86-95), which queries the standard iTunes lookup endpoint to fetch complete metadata including bundle identifiers, version information, and pricing.

5. Output Generation: The function returns a SearchOutput struct containing the final slice of apps, which the CLI renders through the built-in logger at lines 40-44 in cmd/search.go.

Critical Limitations of visionOS Search

Understanding these constraints is essential for production use and automation planning:

Maximum Result Cap: The maxVisionOSSearchResults constant limits all visionOS searches to 12 apps regardless of the --limit flag value passed by the user. This hard ceiling is defined in pkg/appstore/appstore_storefront.go at line 15 and cannot be overridden.

HTML Scraping Dependency: Unlike iOS searches that use stable JSON APIs, visionOS search relies on parsing Apple's storefront HTML. If Apple modifies the page structure or removes the serialized-server-data script element, the serializedServerData function will fail, breaking search functionality without warning.

Purchase Configuration Filter: The containsVisionPurchaseConfiguration check silently excludes apps that do not expose vision-specific purchase metadata in their storefront data. This means some visionOS-compatible apps may not appear in search results despite being available on the platform.

Country-Dependent Results: The visionSearchURL function incorporates the user's storefront country code into the request URL. Accounts linked to storefronts without visionOS support may return empty result sets even for globally available apps.

No Pagination Support: The visionOS implementation does not support pagination parameters. Users receive a single batch of up to 12 results with no mechanism to retrieve additional matches or traverse larger result sets.

Authentication Requirements: While the search itself does not strictly require authentication, the CLI fetches AccountInfo before executing the search (line 20 in cmd/search.go). Users without stored credentials may encounter login prompts even for basic searches.

Practical Usage Examples

Execute visionOS searches using the following command patterns:

# Basic search with default limit (capped at 12)

ipatool search "spatial drawing" --platform visionos

# Maximum results (cannot exceed 12)

ipatool search "AR collaboration" --platform visionos --limit 12

# JSON output for scripting and automation

ipatool search "medical visualization" --platform visionos -o json

The JSON output format follows this structure:

{
  "count": 3,
  "apps": [
    {
      "id": 123456789,
      "bundleID": "com.example.spatialdraw",
      "name": "Spatial Draw"
    },
    {
      "id": 987654321,
      "bundleID": "com.example.arbrush",
      "name": "AR Brush"
    }
  ]
}

Summary

• IPATool provides visionOS search capability through the --platform visionos flag, with core logic implemented in cmd/search.go and pkg/appstore/appstore_search.go.
• The search relies on HTML scraping of Apple's public storefront via pkg/appstore/appstore_storefront.go, extracting data from the serialized-server-data script element.
• Results are permanently capped at 12 apps by the maxVisionOSSearchResults constant defined in the storefront module.
• Only apps exposing vision-specific purchase configurations appear in results due to the containsVisionPurchaseConfiguration filter logic.
• The feature depends on Apple's storefront HTML structure remaining stable, making it vulnerable to breaking changes from server-side updates.
• Authentication is required despite the search being publicly accessible, as the CLI validates AccountInfo before execution.

Frequently Asked Questions

Why can't I get more than 12 results when searching for visionOS apps?

The maxVisionOSSearchResults constant in pkg/appstore/appstore_storefront.go hard-codes a limit of 12 results for all visionOS queries. This limitation exists because Apple's public storefront pages for visionOS only expose a maximum of 12 apps per search term, and IPATool does not implement pagination or offset parameters for this platform.

Does IPATool use the official App Store API for visionOS searches?

No. According to the source code in pkg/appstore/appstore_search.go, visionOS searches use the searchVisionOS function which scrapes Apple's public storefront HTML rather than the iTunes Search API used for iOS and iPadOS. The tool extracts JSON data embedded in the serialized-server-data script tag to retrieve app information.

Why do some visionOS apps not appear in search results?

IPATool filters search results using the containsVisionPurchaseConfiguration function, which checks for specific visionOS purchase metadata in the storefront response. Apps that do not declare this configuration in their storefront data are silently excluded, even if they are compatible with visionOS devices.

Is authentication required to search for visionOS apps?

Technically, the search itself does not require authentication, but the CLI enforces account validation. As implemented in cmd/search.go, the searchCmd function retrieves AccountInfo before executing the search, which may prompt for login credentials if no valid session exists.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}