> ## 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.

# Keyword Opportunities

> Discover untapped keyword opportunities for an app

```
GET /v1/aso/opportunities/:appId
```

Find high-value keyword opportunities for an app. Discovers keywords the app doesn't rank for yet (high volume + low difficulty), plus existing keywords where rank can be improved. Sorted by opportunity score — the higher the score, the bigger the potential impact.

***

## Path Parameters

| Name  | Type   | Required | Description                                                                             |
| ----- | ------ | -------- | --------------------------------------------------------------------------------------- |
| appId | string | Yes      | App ID — numeric for Apple (`913335252`), package name for Google (`com.spotify.music`) |

## Query Parameters

| Name     | Type   | Default | Description                                                                      |
| -------- | ------ | ------- | -------------------------------------------------------------------------------- |
| platform | string | `apple` | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country  | string | `us`    | ISO country code (e.g. `us`, `gb`, `de`)                                         |
| lang     | string | `en`    | Google Play language code (used when `platform=google`)                          |

***

## Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/aso/opportunities/913335252?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/opportunities/913335252?country=us",
    {
      headers: { "X-API-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`Found ${data.summary.totalOpportunities} opportunities`);
  console.log(`High priority: ${data.summary.highPriority}`);

  data.opportunities.slice(0, 5).forEach((opp) => {
    console.log(`  "${opp.keyword}" - Score: ${opp.opportunityScore}, Volume: ${opp.volumeScore}, Difficulty: ${opp.difficulty}`);
  });
  ```

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

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

  data = response.json()["data"]
  print(f"Total opportunities: {data['summary']['totalOpportunities']}")
  print(f"High priority: {data['summary']['highPriority']}")

  for opp in data["opportunities"][:5]:
      print(f"  {opp['keyword']}: score={opp['opportunityScore']}, "
            f"volume={opp['volumeScore']}, difficulty={opp['difficulty']}, "
            f"source={opp['source']}")
  ```
</CodeGroup>

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "913335252",
    "country": "us",
    "opportunities": [
      {
        "keyword": "math learning app",
        "volumeScore": 58,
        "difficulty": 32,
        "opportunityScore": 65,
        "currentRank": null,
        "competitorRank": null,
        "source": "suggestion"
      },
      {
        "keyword": "physics simulator",
        "volumeScore": 45,
        "difficulty": 25,
        "opportunityScore": 52,
        "currentRank": null,
        "competitorRank": null,
        "source": "suggestion"
      },
      {
        "keyword": "science quiz",
        "volumeScore": 40,
        "difficulty": 38,
        "opportunityScore": 42,
        "currentRank": 22,
        "competitorRank": null,
        "source": "improvable-rank"
      }
    ],
    "summary": {
      "totalOpportunities": 18,
      "highPriority": 4,
      "mediumPriority": 8,
      "lowPriority": 6
    }
  }
}
```

***

## Opportunity Fields

| Field            | Type         | Description                                              |
| ---------------- | ------------ | -------------------------------------------------------- |
| keyword          | string       | The keyword opportunity                                  |
| volumeScore      | number       | Search volume score (0-100)                              |
| difficulty       | number       | Ranking difficulty (0-100)                               |
| opportunityScore | number       | Composite opportunity score (0-100, higher = better)     |
| currentRank      | number\|null | App's current rank for this keyword (null = not ranking) |
| competitorRank   | number\|null | Competitor's rank if applicable                          |
| source           | string       | How the opportunity was found (see below)                |

### Source Values

| Source            | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `suggestion`      | New keyword from Apple autocomplete suggestions — the app doesn't rank for it yet |
| `improvable-rank` | App already ranks but outside top 10 — has room to improve                        |

## Summary Fields

| Field              | Type   | Description                         |
| ------------------ | ------ | ----------------------------------- |
| totalOpportunities | number | Total number of opportunities found |
| highPriority       | number | Opportunities with score >= 50      |
| mediumPriority     | number | Opportunities with score 25-49      |
| lowPriority        | number | Opportunities with score \< 25      |

***

<Tip>
  **How opportunity score is calculated:**

  `opportunityScore = volumeScore × easeScore × rankBoost`

  * **easeScore** = `100 - difficulty` (easier keywords score higher)
  * **rankBoost** = multiplier based on current rank:
    * Not ranking (null): 0.5 (moderate upside)
    * Rank 11-30: 1.0 (sweet spot — close to top 10)
    * Rank 31+: 0.7 (ranking but far)
    * Top 3: 0.2 (already optimized, low marginal gain)

  Focus on **high-priority opportunities** (score >= 50) first — these are keywords with good volume, low competition, and realistic ranking potential.
</Tip>

<Tip>
  **Best workflow:**

  1. Run [ASO Audit](/docs/aso-audit) to understand your baseline
  2. Use this endpoint to find opportunities
  3. Add target keywords to [Metadata Suggestions](/docs/aso-metadata-suggest) to generate optimized metadata
  4. [Validate](/docs/aso-validate-metadata) the new metadata before submitting
  5. [Track](/docs/track-keyword) keywords to monitor ranking changes over time
</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   | App not found or unavailable  |