---
title: "Return a keyword popularity score"
method: POST
path: "/v1/popularity"
tags: ["Data"]
---

# Return a keyword popularity score

`POST /v1/popularity`

## Request

- Base URL: `https://api.asoskill.com`
- URL: `https://api.asoskill.com/v1/popularity`
- Auth: HTTP bearer

Returns a 1–100 popularity score from the best available signal. When Apple censors a low direct value, an exact normalized term appearing before the full iPhone autocomplete query can conservatively raise the result to 6–10; it never lowers a stronger score or exceeds 10. Prefix and derived evidence are cached for 30 days independently from the eight-hour base popularity cache. A long cold prefix curve may finish in the background and affect a later request. A successful response costs one credit.

## Request body

- PopularityRequest
  - `term` string, required
  - `storefront` string: Two-letter App Store storefront code; normalized to uppercase

## Response `200`

Popularity result; costs one credit

- PopularityResponse
  - `term` string, required
  - `storefront` string, required
  - `score` integer, required
  - `source` 'monthly' | 'direct' | 'related' | 'autocomplete' | 'fallback', required: Autocomplete means a conservative low-volume estimate based on the exact term appearing before the full query; raw prefixes and censored Apple values are not exposed.
  - `resolution` 'final' | 'pending', required: Pending means background autocomplete evidence is still being collected and the score may improve on a later request. Cache only final results with the normal freshness policy.
  - `scoreVersion` integer, required: Version of the popularity resolution model used for this response.
  - `retryAfterSeconds` integer: Suggested delay before checking a pending result again.
  - `cache` 'hit' | 'refresh' | 'stale', required
  - `fetchedAt` string, date-time, required
  - `requestId` string, required

## Other responses

- `400`: The request body or parameters are invalid; no credit is consumed
- `401`: The bearer credential is missing, invalid, expired, or revoked; no credit is consumed
- `402`: No promotional or paid credits remain; no credit is consumed
- `409`: A concurrent credit reservation could not be completed; no credit is consumed and the request may be retried
- `429`: Request capacity or a rate allowance was exceeded; no credit is consumed. Respect Retry-After when present, otherwise retry with exponential backoff and jitter.
- `500`: Unexpected processing failure; any reserved credit is restored
- `502`: An upstream App Store service failed; any reserved credit is restored
- `503`: ASO Skill or an upstream service is temporarily unavailable; any reserved credit is restored. Retry after the indicated delay when provided.

---

[API](https://skmtc.dev/asoskill/apis/aso-skill-developer-api.md) · [All operations](https://skmtc.dev/asoskill/apis/aso-skill-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asoskill/apis/aso-skill-developer-api/revisions/c9808e5357cf?raw)