app_store.categories
stable Standard
App Store app categories (genre ids and names) for a storefront.
GET /v1/app_store/categories
What you get#
A list of App Store results in Onekey's unified shape, in data (an array). An empty array is a normal, successful answer and is charged like any other; a source that reports "nothing found" as an error returns a free 404 not_found instead.
What it costs#
- Standard · 1 credit for a fresh fetch, charged only when it succeeds.
- Free when served from cache (0.2 credit for a cached response over 100 KB).
- Free if the request is invalid (never charged) or the source fails or reports not found (refunded).
Parameters#
| Name | Type | Required | Default | What it is | Constraints |
|---|---|---|---|---|---|
country | string | no | us | Two-letter storefront country code | max 2 chars; must match [a-z]{2}; trimmed, lowercased |
Request#
curl "https://api.onekey.dev/v1/app_store/categories?country=us" \
-H "x-api-key: YOUR_API_KEY"Try it
Add your key to run this call right here. No key? Get one free. The key stays in this tab.
Recorded response#
No recorded response is published for this endpoint yet.
Field mapping#
How this endpoint's source fields become Onekey's unified schema. Fields the source lacks come back as null.
| Source path | Onekey field | Transform |
|---|---|---|
id | entity.id | - |
name | entity.name | - |
url | entity.url | safeUrl |
Caching and freshness#
- Fresh for about 1 hour. Repeat calls in that window are served from cache and are free.
- Between 1 hour and 1 day the cached copy is still served instantly and marked
stale: truewhile Onekey refreshes it in the background. - If the source is down when a refresh is needed, the last copy can be served for up to 3 days more (marked stale).
- A "not found" is remembered for 5 minutes and is free.
- The cache is shared across all customers, which is what keeps repeat calls cheap.
What can go wrong#
| Status | Code | What to do |
|---|---|---|
| 401 | unauthorized | Check the x-api-key header. |
| 402 | insufficient_credits | Add credits; your balance must cover the price. |
| 404 | not_found | Unknown endpoint path. |
| 422 | invalid_params | Fix the parameters using the table above. Free. |
| 429 | rate_limited | Wait Retry-After seconds, then retry. |
| 502 | upstream_error | The source failed. Refunded; retry with backoff. |
See Errors for the full list and retry guidance.
Status: stable (verified against the live source).