> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Competitor ASO Report

> Deep ASO comparison between two apps with keyword gap analysis

```
GET /v1/aso/competitor/:appId/:competitorId
```

Deep App Store Optimization comparison between two apps. Returns side-by-side profiles (rating, reviews, metadata quality, visuals, localization), keyword overlap analysis, gap opportunities, and a strategic verdict.

This is a higher-level analysis than [Keyword Compare](/docs/keyword-compare) — it includes metadata comparison, visual asset analysis, and an overall competitive assessment.

***

## Path Parameters

| Name         | Type   | Required | Description               |
| ------------ | ------ | -------- | ------------------------- |
| appId        | string | Yes      | Your app's Apple App ID   |
| competitorId | string | Yes      | Competitor's Apple App ID |

## Query Parameters

| Name    | Type   | Default | Description                              |
| ------- | ------ | ------- | ---------------------------------------- |
| country | string | `us`    | ISO country code (e.g. `us`, `gb`, `de`) |

***

## Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/aso/competitor/913335252/1157115554?country=us" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.appeeky.com/v1/aso/competitor/913335252/1157115554?country=us",
    {
      headers: { "X-API-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`Your app: ${data.yourApp.title} (${data.yourApp.rating}★)`);
  console.log(`Competitor: ${data.competitorApp.title} (${data.competitorApp.rating}★)`);
  console.log(`Keyword overlap: ${data.keywordAnalysis.overlapPercent}%`);
  console.log(`Gaps to target: ${data.keywordAnalysis.gaps}`);
  console.log(`Verdict: ${data.verdict}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.appeeky.com/v1/aso/competitor/913335252/1157115554",
      params={"country": "us"},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

  data = response.json()["data"]
  print(f"Your app: {data['yourApp']['title']} ({data['yourApp']['rating']}★)")
  print(f"Competitor: {data['competitorApp']['title']} ({data['competitorApp']['rating']}★)")
  print(f"Keyword overlap: {data['keywordAnalysis']['overlapPercent']}%")
  print(f"\nTop keyword gaps:")
  for gap in data["keywordAnalysis"]["topGaps"][:5]:
      print(f"  {gap['keyword']}: rank #{gap['competitorRank']}, volume {gap['volumeScore']}")
  print(f"\nVerdict: {data['verdict']}")
  ```
</CodeGroup>

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "913335252",
    "competitorId": "1157115554",
    "country": "us",
    "yourApp": {
      "appId": "913335252",
      "title": "Brilliant: Learn by doing",
      "developer": "Brilliant.org",
      "icon": "https://is1-ssl.mzstatic.com/.../512x512bb.jpg",
      "rating": 4.74,
      "reviews": 27315,
      "category": "Education",
      "titleLength": 25,
      "descriptionLength": 1250,
      "screenshotCount": 6,
      "languageCount": 1,
      "lastUpdated": "2026-01-26T12:19:36Z"
    },
    "competitorApp": {
      "appId": "1157115554",
      "title": "Khan Academy",
      "developer": "Khan Academy",
      "icon": "https://is1-ssl.mzstatic.com/.../512x512bb.jpg",
      "rating": 4.8,
      "reviews": 158000,
      "category": "Education",
      "titleLength": 12,
      "descriptionLength": 2100,
      "screenshotCount": 8,
      "languageCount": 15,
      "lastUpdated": "2026-02-10T08:00:00Z"
    },
    "comparison": {
      "ratingDiff": -0.06,
      "reviewsDiff": -130685,
      "titleLengthDiff": 13,
      "descriptionLengthDiff": -850,
      "screenshotCountDiff": -2,
      "languageCountDiff": -14
    },
    "keywordAnalysis": {
      "shared": 5,
      "yourUnique": 3,
      "competitorUnique": 8,
      "gaps": 2,
      "overlapPercent": 31,
      "topGaps": [
        { "keyword": "free courses", "competitorRank": 3, "volumeScore": 65 },
        { "keyword": "learn coding", "competitorRank": 5, "volumeScore": 58 },
        { "keyword": "khan academy", "competitorRank": 1, "volumeScore": 82 },
        { "keyword": "online learning", "competitorRank": 8, "volumeScore": 55 },
        { "keyword": "study app", "competitorRank": 12, "volumeScore": 48 }
      ]
    },
    "verdict": "Competitor leads in: more reviews, broader keyword coverage. Your strengths: niche keyword positions. Target their 8 unique keywords for quick wins."
  }
}
```

***

## App Profile Fields

Each app profile (`yourApp` and `competitorApp`) includes:

| Field             | Type   | Description                   |
| ----------------- | ------ | ----------------------------- |
| appId             | string | Apple App ID                  |
| title             | string | App name                      |
| developer         | string | Developer name                |
| icon              | string | App icon URL                  |
| rating            | number | Star rating (0-5)             |
| reviews           | number | Total review count            |
| category          | string | Primary category              |
| titleLength       | number | Title character count         |
| descriptionLength | number | Description character count   |
| screenshotCount   | number | Number of screenshots         |
| languageCount     | number | Number of supported languages |
| lastUpdated       | string | Last update date (ISO 8601)   |

## Comparison Fields

Difference values: **positive = your app is higher**, negative = competitor is higher.

| Field                 | Type   | Description                                       |
| --------------------- | ------ | ------------------------------------------------- |
| ratingDiff            | number | Rating difference (yourRating - competitorRating) |
| reviewsDiff           | number | Review count difference                           |
| titleLengthDiff       | number | Title length difference (chars)                   |
| descriptionLengthDiff | number | Description length difference (chars)             |
| screenshotCountDiff   | number | Screenshot count difference                       |
| languageCountDiff     | number | Language count difference                         |

## Keyword Analysis Fields

| Field            | Type   | Description                                        |
| ---------------- | ------ | -------------------------------------------------- |
| shared           | number | Keywords both apps rank for                        |
| yourUnique       | number | Keywords only your app ranks for                   |
| competitorUnique | number | Keywords only the competitor ranks for             |
| gaps             | number | Keywords where competitor outranks you             |
| overlapPercent   | number | Percentage of keywords shared (0-100)              |
| topGaps          | array  | Top 10 competitor-unique keywords sorted by volume |

### Top Gap Entry

| Field          | Type   | Description                          |
| -------------- | ------ | ------------------------------------ |
| keyword        | string | The keyword the competitor ranks for |
| competitorRank | number | Competitor's rank position           |
| volumeScore    | number | Search volume score (0-100)          |

***

<Tip>
  **How to use this report:**

  1. **Close keyword gaps** — Target `topGaps` keywords with high volume in your next metadata update
  2. **Fix weak areas** — If `screenshotCountDiff` or `languageCountDiff` is negative, improve visuals or add localizations
  3. **Leverage strengths** — If your `ratingDiff` is positive, mention it in marketing. If `yourUnique` keywords are high-value, protect those positions
  4. **Read the verdict** — The automated summary highlights the most important competitive dynamics
</Tip>

***

## Errors

| Status | Code              | When                          |
| ------ | ----------------- | ----------------------------- |
| 400    | INVALID\_APP\_ID  | Non-numeric or missing app ID |
| 401    | MISSING\_API\_KEY | No API key in the request     |
| 404    | APP\_NOT\_FOUND   | One or both apps not found    |