---
title: "Search the App Store and calculate keyword difficulty"
method: POST
path: "/v1/search"
tags: ["Data"]
---

# Search the App Store and calculate keyword difficulty

`POST /v1/search`

## Request

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

Returns ordered App Store results and a 0–100 difficulty score. Results are fresh for one hour; a stale fallback is never older than 24 hours. Optional app-detail enrichment may be omitted when Apple throttles it. A successful response costs one credit.

## Request body

- SearchRequest
  - `term` string, required
  - `storefront` string: Two-letter App Store storefront code; normalized to uppercase
  - `platform` 'iphone' | 'ipad' | 'mac' | 'appletv' | 'watch' | 'vision'

## Response `200`

Search result; costs one credit

- SearchResponse
  - `term` string, required
  - `storefront` string, required
  - `platform` 'iphone' | 'ipad' | 'mac' | 'appletv' | 'watch' | 'vision', required
  - `difficulty` integer, required
  - `resultCount` integer, required
  - `results` SearchResult[], required
    - `position` integer, required
    - `appId` string, required
    - `name` string, required
    - `subtitle` string
    - `developer` string
    - `rating` number
    - `ratingCount` integer
    - `categoryRank` integer
    - `category` string
    - `url` string, uri
    - `icon` string, uri
  - `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)