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

# Suggest Metadata

> Generate optimized app store metadata based on keyword data

```
POST /v1/aso/metadata/suggest
```

Generate optimized metadata suggestions for an app based on target keywords. Returns character-validated suggestions for both Apple App Store (title, subtitle, keyword field) and Google Play Store (title, short description), backed by real keyword volume and difficulty data.

***

## Request Body

| Field    | Type      | Required | Default | Description                                        |
| -------- | --------- | -------- | ------- | -------------------------------------------------- |
| appId    | string    | Yes      | —       | Apple App ID (numeric)                             |
| keywords | string\[] | Yes      | —       | Target keywords to optimize for (2-10 recommended) |
| country  | string    | No       | `us`    | ISO country code                                   |

***

## Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/aso/metadata/suggest" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "appId": "913335252",
      "keywords": ["learn math", "science education", "puzzle solving", "brain training"],
      "country": "us"
    }'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.appeeky.com/v1/aso/metadata/suggest",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        appId: "913335252",
        keywords: ["learn math", "science education", "puzzle solving", "brain training"],
        country: "us",
      }),
    }
  );

  const { data } = await response.json();
  console.log("Apple title:", data.apple.title.text);
  console.log("Apple subtitle:", data.apple.subtitle.text);
  console.log("Apple keywords:", data.apple.keywords.text);
  console.log("Google title:", data.google.title.text);
  ```

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

  response = requests.post(
      "https://api.appeeky.com/v1/aso/metadata/suggest",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={
          "appId": "913335252",
          "keywords": ["learn math", "science education", "puzzle solving", "brain training"],
          "country": "us",
      },
  )

  data = response.json()["data"]
  print(f"Apple Title: {data['apple']['title']['text']} ({data['apple']['title']['charCount']}/{data['apple']['title']['maxChars']})")
  print(f"Apple Keywords: {data['apple']['keywords']['text']}")
  ```
</CodeGroup>

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "apple": {
      "title": {
        "text": "Brilliant: Learn Math",
        "charCount": 21,
        "maxChars": 30
      },
      "subtitle": {
        "text": "Science Education & Puzzles",
        "charCount": 27,
        "maxChars": 30
      },
      "keywords": {
        "text": "training,brain,solving,puzzle,education,science,interactive,quiz,study",
        "charCount": 69,
        "maxChars": 100,
        "keywordCount": 9
      }
    },
    "google": {
      "title": {
        "text": "Brilliant - Learn Math & Science Education",
        "charCount": 43,
        "maxChars": 50
      },
      "shortDescription": {
        "text": "Brilliant helps you with learn math and science education. Download now!",
        "charCount": 71,
        "maxChars": 80
      }
    },
    "targetKeywords": [
      { "keyword": "learn math", "volumeScore": 62, "difficulty": 45 },
      { "keyword": "brain training", "volumeScore": 55, "difficulty": 52 },
      { "keyword": "science education", "volumeScore": 38, "difficulty": 30 },
      { "keyword": "puzzle solving", "volumeScore": 28, "difficulty": 35 }
    ]
  }
}
```

***

## Response Fields

### Apple Metadata

| Field                       | Type   | Description                                   |
| --------------------------- | ------ | --------------------------------------------- |
| apple.title.text            | string | Suggested title (max 30 chars)                |
| apple.title.charCount       | number | Character count                               |
| apple.subtitle.text         | string | Suggested subtitle (max 30 chars)             |
| apple.keywords.text         | string | Comma-separated keyword field (max 100 chars) |
| apple.keywords.keywordCount | number | Number of keywords in the field               |

### Google Metadata

| Field                        | Type   | Description                                |
| ---------------------------- | ------ | ------------------------------------------ |
| google.title.text            | string | Suggested title (max 50 chars)             |
| google.shortDescription.text | string | Suggested short description (max 80 chars) |

### Target Keywords

| Field       | Type   | Description                      |
| ----------- | ------ | -------------------------------- |
| keyword     | string | The target keyword               |
| volumeScore | number | Search volume score (0-100)      |
| difficulty  | number | Ranking difficulty score (0-100) |

***

<Tip>
  **How suggestions are generated:**

  * Keywords are sorted by volume score (highest first) for prioritization
  * The **top keyword** goes into the title with the brand name
  * The **2nd-3rd keywords** form the subtitle
  * The **keyword field** excludes words already in the title (Apple's guideline: don't repeat title words in keywords)
  * All suggestions are **character-validated** before being returned
</Tip>

<Warning>
  These are **algorithmic suggestions** based on keyword data. Always review and refine them for natural language and brand voice before submitting to the store. The best metadata reads naturally to humans while incorporating high-value keywords.
</Warning>

***

## Errors

| Status | Code              | When                         |
| ------ | ----------------- | ---------------------------- |
| 400    | INVALID\_APP\_ID  | Non-numeric or missing appId |
| 400    | INVALID\_KEYWORDS | keywords is missing or empty |
| 401    | MISSING\_API\_KEY | No API key in the request    |
| 404    | APP\_NOT\_FOUND   | App not found or unavailable |