appstore-intel

# App Store Intelligence

Look up app details, ratings, reviews, and search the iOS App Store and Mac App Store using Apple's free iTunes Search & Lookup APIs. No API key required.

For Google Play, use web scraping via `web_search` and `web_fetch`.

## When to Use

- User asks about an app's ratings or reviews
- User wants to compare apps in a category
- User wants to find apps by keyword
- User asks about a competitor's app store presence
- User wants app metadata (price, size, version, release notes)

## API Overview — Apple iTunes Search API

**Free. No authentication. No API key.**

Two endpoints:
- **Search:** `https://itunes.apple.com/search`
- **Lookup:** `https://itunes.apple.com/lookup`

**Rate Limit:** ~20 calls per minute. Cache results for heavy usage.

## Searching for Apps

### Basic Search

```
https://itunes.apple.com/search?term=QUERY&country=COUNTRY&entity=software&limit=N
```

Use `web_fetch` to call this URL. Response is JSON.

### Parameters

| Parameter | Description | Required | Values |
|-----------|-------------|----------|--------|
| `term` | Search query (URL-encoded, `+` for spaces) | Yes | Any text |
| `country` | Two-letter country code | Yes | `us`, `gb`, `de`, etc. |
| `entity` | App type | No | `software` (iPhone), `iPadSoftware`, `macSoftware` |
| `media` | Media type | No | `software` (default for apps) |
| `limit` | Max results | No | 1–200 (default 50) |
| `lang` | Language | No | `en_us`, `ja_jp` |

### Example

```
https://itunes.apple.com/search?term=fitness+tracker&country=us&entity=software&limit=10
```

## Looking Up Specific Apps

### By App ID (Track ID)

```
https://itunes.apple.com/lookup?id=APP_ID&country=us
```

### By Bundle ID

```
https://itunes.apple.com/lookup?bundleId=com.example.app&country=us
```

### Multiple Apps at Once

```
https://itunes.apple.com/lookup?id=ID1,ID2,ID3&country=us
```

## Response Format

Each result contains:

```json
{
  "trackId": 553834731,
  "trackName": "App Name",
  "bundleId": "com.example.app",
  "sellerName": "Company Name",
  "artistName": "Developer Name",
  "price": 0.00,
  "formattedPrice": "Free",
  "currency": "USD",
  "averageUserRating": 4.5,
  "userRatingCount": 125000,
  "averageUserRatingForCurrentVersion": 4.3,
  "userRatingCountForCurrentVersion": 5000,
  "contentAdvisoryRating": "4+",
  "trackContentRating": "4+",
  "primaryGenreName": "Health & Fitness",
  "genres": ["Health & Fitness", "Lifestyle"],
  "description": "Full app description...",
  "releaseNotes": "What's new in this version...",
  "version": "3.2.1",
  "currentVersionReleaseDate": "2024-01-10T00:00:00Z",
  "releaseDate": "2020-06-15T00:00:00Z",
  "fileSizeBytes": "52428800",
  "minimumOsVersion": "15.0",
  "trackViewUrl": "https://apps.apple.com/us/app/...",
  "artworkUrl512": "https://is1-ssl.mzstatic.com/...",
  "screenshotUrls": ["url1", "url2"],  // ⚠️ Can be 10+ URLs — summarize count, don't dump all
  "supportedDevices": ["iPhone15,2", "iPad14,1"],  // ⚠️ Can be 100+ items — omit from output to save context
  "languageCodesISO2A": ["EN", "FR", "DE"]
}
```

The response wrapper:
```json
{
  "resultCount": 10,
  "results": [...]
}
```

## Google Play Lookup

There's no free public Google Play API. Use these approaches:

### Web Search

```
web_search: "site:play.google.com/store/apps QUERY"
```

### Direct App Page Scraping

```
web_fetch: https://play.google.com/store/apps/details?id=PACKAGE_ID&hl=en&gl=us
```

⚠️ **Google Play pages may return limited content or block automated requests.** If `web_fetch` returns incomplete data, fall back to `web_search` results which typically include rating, download count, and developer info in the snippet.

Extract from the fetched HTML (when available):
- Title, developer, rating, review count, downloads
- Description, what's new, screenshots

### Google Play Package ID

The package ID is in the URL: `play.google.com/store/apps/details?id=com.example.app`

## Step-by-Step Instructions

### Search for Apps by Keyword

1. URL-encode the search term
2. Fetch: `https://itunes.apple.com/search?term=ENCODED_QUERY&country=us&entity=software&limit=10`
3. Parse JSON response
4. For each result, present: name, developer, rating, review count, price, and App Store link

### Get Detailed Info for a Specific App

1. Find the app's Track ID (from a search, or from the App Store URL — the number after `/id`)
2. Fetch: `https://itunes.apple.com/lookup?id=TRACK_ID&country=us`
3. Present full details: rating, reviews, version, release notes, price, size, description

### Compare Two Apps

1. Look up both apps: `https://itunes.apple.com/lookup?id=ID1,ID2&country=us`
2. Present side-by-side comparison of key metrics

### Check an App's Rating Across Countries

1. Look up the same ID with different country codes:
   - `https://itunes.apple.com/lookup?id=APP_ID&country=us`
   - `https://itunes.apple.com/lookup?id=APP_ID&country=gb`
   - `https://itunes.apple.com/lookup?id=APP_ID&country=de`
2. Compare ratings and review counts by region

### Find Both iOS and Android Versions

1. Search iOS: iTunes Search API with the app name
2. Search Android: `web_search "site:play.google.com/store/apps APP_NAME"`
3. Fetch the Google Play page with `web_fetch` for details
4. Present both platforms' data

## Finding App IDs

- **From App Store URL:** `apps.apple.com/us/app/app-name/id553834731` → ID is `553834731`
- **From search results:** The `trackId` field
- **From bundle ID lookup:** If you know the bundle ID (e.g., `com.spotify.client`)

## Output Format

### Single App

```
### App Name
⭐ 4.5/5 (125K ratings) · Free
By Developer Name · Health & Fitness
Version 3.2.1 (Jan 10, 2024)

📝 What's New: Latest release notes summary...

📱 iOS: https://apps.apple.com/...
🤖 Android: https://play.google.com/...
```

### Search Results

```
### App Store Results for "query" (N found)

1. **App Name** ⭐ 4.5 (125K) · Free
   By Developer · Category
   📱 https://apps.apple.com/...

2. **App Name** ⭐ 4.2 (50K) · $4.99
   By Developer · Category
   📱 https://apps.apple.com/...
```

### Comparison

```
### App Comparison

| Metric | App A | App B |
|--------|-------|-------|
| Rating | ⭐ 4.5 | ⭐ 4.2 |
| Reviews | 125K | 50K |
| Price | Free | $4.99 |
| Size | 50 MB | 120 MB |
| Last Updated | Jan 10, 2024 | Dec 5, 2023 |
```

## Error Handling

- **No results:** The search term may be too specific. Try broader terms or check spelling.
- **API error / timeout:** Retry once. The iTunes API is generally reliable.
- **Rate limited:** Wait 60 seconds. Consider caching results for batch lookups.
- **Country not found:** Verify the two-letter ISO country code.
- **App removed from store:** The lookup will return `resultCount: 0`. Inform the user the app may have been removed.
- **Google Play scraping fails:** The page structure may have changed. Fall back to `web_search` results.

## Examples

### Example 1: "How's the Spotify app rated?"

```
Fetch: https://itunes.apple.com/lookup?bundleId=com.spotify.client&country=us
```

### Example 2: "Find fitness apps with good ratings"

```
Fetch: https://itunes.apple.com/search?term=fitness&country=us&entity=software&limit=20
```
Then filter results where `averageUserRating >= 4.5` and sort by `userRatingCount`.

### Example 3: "Compare Notion and Obsidian on the App Store"

Look up both apps and present a comparison table.

## Data Sources

- **iOS / Mac:** [iTunes Search API](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/) — Free, no auth
- **Android:** Google Play Store web pages via `web_fetch` — Free, no auth, scraping