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

> Brainstorm up to 20 new search queries an app could rank for, grouped by intent, from its live store listing.

**Keyword Ideas** reads an app's App Store or Google Play listing and suggests search queries it could rank for but doesn't target yet. Each idea is tagged with the kind of search it represents, so you can spread your keyword field across intents instead of picking near-duplicates.

Use the ideas as a starting list. Check their volume and difficulty with [Keyword Metrics](https://docs.appeeky.com/docs/keyword-metrics.md) before you add them to your metadata.

> [!NOTE]
>
> Requires a paid plan. Uses 0 credits, limited to **10 requests per hour** per account or API key.

***

## API

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/keywords/ideas` | Generate keyword ideas for one app |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/keywords/ideas \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "123456789",
    "platform": "apple",
    "country": "us",
    "limit": 10,
    "exclude": ["habit tracker"],
    "hint": "morning routines for students"
  }'
```

| Field | Type | Description |
| - | - | - |
| `appId` | string | Required. App Store numeric id or Google Play package name |
| `platform` | string | `apple` (default) or `google` |
| `country` | string | 2-letter storefront code. Default `us` |
| `limit` | number | Ideas to return, 1–20. Default `20` |
| `exclude` | string\[] | Keywords to leave out, such as ones you already track. Up to 100 |
| `hint` | string | Optional theme to steer the ideas, up to 200 characters |

Response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "123456789",
    "platform": "apple",
    "country": "us",
    "persona": "Students who want to build a steady morning routine",
    "ideas": [
      { "keyword": "morning routine planner", "bucket": "use_case" },
      { "keyword": "habit app for students", "bucket": "audience" },
      { "keyword": "streaks alternative", "bucket": "alternative" }
    ]
  }
}
```

`persona` is the audience the ideas were written for. `bucket` is one of:

| Bucket | Example |
| - | - |
| `direct` | "habit tracker" |
| `alternative` | "streaks alternative" |
| `use_case` | "track daily water intake" |
| `audience` | "habit app for students" |
| `feature` | "habit widget" |
| `long_tail` | "how to stop procrastinating every morning" |

`bucket` can be `null` when an idea doesn't fit one clearly.

***

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_BODY` | A field is missing or out of range |
| 400 | `INVALID_APP_ID` | `appId` doesn't match the platform's id format |
| 403 | `PRO_FEATURE` | Your plan doesn't include this feature |
| 404 | `APP_NOT_FOUND` | The store listing couldn't be loaded |
| 429 | `RATE_LIMITED` | More than 10 requests in the last hour. `Retry-After` says when to try again |

***

## Tips

* Pass the keywords you already track in `exclude` so every idea is new.
* Run it per country. Ideas follow the storefront you pick.
* Use `hint` to explore one angle at a time, for example a feature you just shipped.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.