# App Store 竞品应用 API (app_store.competitors)

- Canonical page: https://everyinfra.com/app-store-api/competitors
- Endpoint: POST /api/v1/social with {"platform": "app_store", "action": "competitors", "params": {...}}
- Price: $0.01151 per call ($11.51 per 1,000 requests); failed and empty results are not charged
- Returns: list, default 20, max 100 per call (larger values are capped)
- Mode: sync; add "mode": "async" for slow tasks

App Store 竞品应用按 `app_id` 找出和目标应用关键词重叠最多的竞品，每个竞品一行：共同关键词个数 `shared_keywords`、竞品在这些词下的平均名次 `avg_position`、其中排进前 10 的个数 `shared_top10_keywords`，以及这些词的月搜索量合计。它回答「在关键词上，真正的对手是谁」，适合找没想到的对手。

`app_id` 填 Apple 的数字应用 ID，也可以放完整的 App Store 应用链接，不是 com.example.app 这种 Bundle ID。结果按 `shared_keywords` 从多到少排；`country` 只能是美国站。对手已知、要比整体体量时，用批量排名指标。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=app_store&action=competitors

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| app_id | not declared | yes | not declared | Apple 的数字应用 ID，例如应用链接中 id 后的数字；也可将完整 App Store 应用链接放入此参数，系统提取数字 ID。不是 com.example.app 形式的 Bundle ID。 |
| country | not declared | no | not declared | App Store 店面国家/地区：只支持 us（美国站，默认），传别的国家在扣费前被拒。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限照收，按上限返回。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| app_id | App Store 数字 ID。 |
| shared_keywords | 这个竞品和目标 App 都排得上的关键词个数（competitors），按它从多到少排。 |
| avg_position | 竞品在共同关键词下的平均名次（competitors），越小越靠前。 |
| shared_top10_keywords | 共同关键词里，竞品排进前 10 的个数（competitors）。 |
| shared_search_volume | 共同关键词的月搜索量合计（competitors）。 |
| keyword_count | 这个 App 排得上的关键词总数（bulk_metrics、competitors）。 |
| top10_keywords | 排进前 10 的关键词个数（bulk_metrics、competitors，含前 3）。 |
| target_app_id | 这次查的目标 App（competitors），每行相同。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "app_store",
  "action": "competitors",
  "params": {
    "app_id": "389801252"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "app_store",
        "action": "competitors",
        "params": {
            "app_id": "389801252",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

No real sample for these example parameters yet: structure only, every value is a placeholder (…).

```text
{
  "id": "req_…",
  "platform": "app_store",
  "action": "competitors",
  "results": [
    {
      "app_id": …,
      "shared_keywords": …,
      "avg_position": …,
      "shared_top10_keywords": …,
      "shared_search_volume": …,
      "keyword_count": …,
      "top10_keywords": …,
      "target_app_id": …,
      "platform": …
    }
  ],
  "count": …,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `app_id` 可以填 Bundle ID 或应用链接吗？

填完整的 App Store 应用链接可以，系统会提取数字 ID；Bundle ID 不接受，com.example.app 这种写法不能用。最稳的是直接填应用链接里 id 后面那串数字。

### 竞品是按什么顺序排的？

按 `shared_keywords` 从多到少，也就是和目标应用共同关键词最多的排最前。`avg_position` 单独看，越小越靠前；共同词最多的竞品，名次不一定最靠前，两个数要一起读。

### `shared_top10_keywords` 和 `top10_keywords` 有什么不同？

`shared_top10_keywords` 只数共同关键词里竞品排进前 10 的个数；`top10_keywords` 数这个竞品所有关键词里排进前 10 的个数，含前 3。`target_app_id` 是你查的目标应用，每行相同。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=app_store
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md