# Apple App Store (/docs/app_store)

App Store search, app detail, user reviews, store charts, autocomplete suggestions, and a paginated listings database

App Store intelligence without an Apple developer account: keyword search, full app records, user reviews, the store charts, the autocomplete suggestions Apple shows in its own search box, and a filterable listings database you can page deeply.

Base URL: `/v1/app_store/...`

Every app read starts from Apple's **numeric app id**, the number after `id` in an `apps.apple.com/…/id324684580` URL. `app-search` is how you turn an app name into one.

  Storefront changes the answer, not just the language. Ratings, review text,
  charts and even availability differ per country, so a cross-market comparison
  means one call per `country`, not one call plus a `language` change.

## Quickstart

### Turn an app name into an app id

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/app_store/app-search?query=photo%20editor&country=US" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read the full record and what users say

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/app_store/app-info?app_id=324684580" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/app_store/app-reviews?app_id=324684580&sort_by=most_helpful&depth=200" \
  -H "x-api-key: YOUR_API_KEY"
```

## Finding apps

| Endpoint                                | Credits | What it returns                                                                                     | Key parameters                                                                                         |
| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `GET /v1/app_store/app-search`          | 5       | Keyword matches with title, icon, rating, price or free flag, store URL                             | `query` (required), `country`, `language`, `depth`                                                     |
| `GET /v1/app_store/app-listings-search` | 10      | The same app shape from a filterable listings database, with a store-wide total alongside each page | `title` (required), `description`, `limit`, `offset`, `offset_token`, `filters`, `country`, `language` |
| `GET /v1/app_store/search-suggestions`  | 1       | Apple's own autocomplete hints for a partial keyword, each with its rank in Apple's ordering        | `query` (required), `country`                                                                          |

On `app-search`, `depth` defaults to 100, rounds up to multiples of 100, and caps at 300.

`app-listings-search` is the only App Store endpoint with real pagination: `limit` runs 1 to 50, `offset` up to 10,000, and `offset_token` carries you past that. It also accepts a `filters` expression as a JSON array. Ten credits is the price of being able to enumerate rather than sample.

`search-suggestions` returns `{ term, priority }` where `priority` is Apple's own 1-based rank. Polling a stem daily and diffing the list is a cheap way to catch a rising search term before it shows up in the charts.

## App detail and reviews

| Endpoint                        | Credits | What it returns                                                                                        | Key parameters                                                           |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `GET /v1/app_store/app-info`    | 5       | Description, developer, rating, price, version, minimum iOS version, size, screenshots, age advisories | `app_id` (required), `country`, `language`                               |
| `GET /v1/app_store/app-reviews` | 5       | Star rating, review title, full text, reviewer name, publish date                                      | `app_id` (required), `depth`, `sort_by`, `rating`, `country`, `language`, `label`, `judgments` |

Reviews arrive in batches of 50 up to a ceiling of 600. `sort_by` selects `most_recent` (default) or `most_helpful`, and `rating` filters to a single star value, which is the fastest route to the one-star complaints if that is what you are mining.

## Charts

| Endpoint                     | Credits | What it returns                                                                  | Key parameters                                                              |
| ---------------------------- | ------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `GET /v1/app_store/app-list` | 5       | A store chart in the same app shape as search, optionally scoped to one category | `app_collection` (required), `app_category`, `depth`, `country`, `language` |

`app_collection` accepts `top_free_ios`, `top_paid_ios`, `top_grossing_ios`, `top_free_ipad`, `top_paid_ipad`, `top_grossing_ipad`, `new_ios`, `new_free_ios` and `new_paid_ios`. `depth` runs up to 500.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/app_store/app-list?app_collection=top_free_ios&app_category=photo_and_video&country=KR" \
  -H "x-api-key: YOUR_API_KEY"
```

## Reference lookups

| Endpoint                       | Credits | What it returns                                         | Key parameters |
| ------------------------------ | ------- | ------------------------------------------------------- | -------------- |
| `GET /v1/app_store/categories` | 1       | The values `app_category` takes on `app-list`           | none           |
| `GET /v1/app_store/locations`  | 1       | Supported storefronts with their numeric location codes | none           |
| `GET /v1/app_store/languages`  | 1       | Supported language codes                                | none           |

Static reference data, cached hard. Call each once and keep the answer.

## All endpoints

## Platform notes

**Reviews are capped at 500.** No parameter raises that ceiling. Above 500 the request is clamped rather than rejected, and a full 500-review pull takes around 40 seconds. If you need a longer history, sample repeatedly over time rather than trying to page past it. Google Play's ceiling is higher, at 600.

**Apple reviews carry no avatar, helpful votes, or developer replies.** Those fields are null here because Apple does not publish them, not because they were dropped. Google Play does carry developer replies.

**`country` accepts three shapes on the app-data endpoints.** An ISO code (`US`), a full country name (`United States`), or a numeric location code (`2840`) all work there, and it defaults to the US. **`search-suggestions` is the exception:** it takes an ISO alpha-2 code only, and anything else is a free 400. Get the numeric codes from `locations`.

**`language` does not change the storefront.** It defaults to `en` everywhere and only affects response language. Use `country` to change which store is queried.

**Cross-store comparison uses the same shapes.** [Google Play](/docs/google_play.md) mirrors this endpoint set with the same names, so one integration covers both stores. The identifier differs: Play uses a package name where Apple uses a numeric id.

## Labels

`/v1/app_store/app-reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and where depth replaces it.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [API reference](/docs/api-reference.md): Every App Store parameter and response field.
- [Google Play](/docs/google_play.md): The same endpoint names for the other store.
- [Trustpilot](/docs/trustpilot.md): Company reviews in the same canonical review shape.