> ## 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 Visibility Score

> Per-app share-of-voice score (0–100) across the keywords it ranks for, with a daily series and top contributors.

```
GET /v1/keywords/visibility
```

A single 0–100 score answering: "how visible is this app across all the keywords it ranks for?" Each keyword the app ranks for contributes `volume_score × rank_weight`, where the rank weight curve favors top-3 placements:

| Rank          | Weight |
| ------------- | ------ |
| 1             | 1.00   |
| 2–3           | 0.85   |
| 4–5           | 0.70   |
| 6–10          | 0.50   |
| 11–20         | 0.30   |
| 21–50         | 0.15   |
| 51–100        | 0.05   |
| >100 / absent | 0      |

The final score is normalized against the union of keywords the app ranked for in the window, so you can compare scores across days.

***

## Query Parameters

| Name    | Type   | Required | Default  | Description                   |
| ------- | ------ | -------- | -------- | ----------------------------- |
| appId   | string | Yes      | —        | Numeric Apple app ID          |
| country | string | No       | `us`     | ISO 3166-1 alpha-2 storefront |
| device  | string | No       | `iphone` | `iphone` or `ipad`            |
| days    | number | No       | `30`     | Window length, 7–90           |

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "123456789",
    "country": "us",
    "device": "iphone",
    "days": 30,
    "score": 47.3,
    "scoreChange": 5.8,
    "series": [
      { "date": "2026-03-22", "score": 41.5, "rankedCount": 29 },
      { "date": "2026-03-23", "score": 42.7, "rankedCount": 31 },
      { "date": "2026-04-21", "score": 47.3, "rankedCount": 33 }
    ],
    "topContributors": [
      { "keyword": "claude ai", "rank": 2, "volumeScore": 74, "contribution": 62.9 },
      { "keyword": "ai assistant", "rank": 5, "volumeScore": 68, "contribution": 47.6 }
    ],
    "breakdown": [
      { "bucket": "top3",  "rankedCount": 4,  "weightedScore": 312.5,  "share": 78.4 },
      { "bucket": "top10", "rankedCount": 11, "weightedScore": 605.0,  "share": 64.1 },
      { "bucket": "top30", "rankedCount": 22, "weightedScore": 812.7,  "share": 47.3 }
    ],
    "breakdownByBucket": {
      "top3":  { "rankedCount": 4,  "weightedScore": 312.5, "share": 78.4 },
      "top10": { "rankedCount": 11, "weightedScore": 605.0, "share": 64.1 },
      "top30": { "rankedCount": 22, "weightedScore": 812.7, "share": 47.3 }
    }
  },
  "meta": {
    "lastScrapedAt": "2026-04-21T00:00:00Z",
    "dataAgeHours": 4,
    "source": "stored",
    "freshness": "fresh"
  }
}
```

`scoreChange` is the difference between the latest and the first day in the window — a positive value means visibility improved.

`breakdown` decomposes today's score into Top-3 / Top-10 / Top-30 buckets so you can see *where* the score is coming from. `share` is on the same 0–100 scale as the top-line score; a Top-3 share much higher than Top-10 means the score is driven by a few hero keywords.

`breakdownByBucket` is the same data as `breakdown`, exposed as a fixed-shape object so clients can read `breakdownByBucket.top3.share` directly without scanning an array. The `breakdown` array is preserved for backward compatibility — both fields are always populated.

The response-level `meta` envelope describes data freshness — see [Keyword Metrics → meta envelope](/docs/keyword-metrics#meta-envelope-response-level) for the schema.

## Credit Cost

3 credits per request.

## Use Cases

* Mobile **Insights** tab headline metric.
* Weekly ASO report opener: "Visibility is up 5.8 points week over week."
* Competitor benchmarking when called against multiple `appId`s.