# Apple App Store (/docs/app_store)



Apple App Store [#apple-app-store]

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. Everything is storefront-aware, so the
same query answers differently for the US, Korea or Brazil.

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.

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header.

```bash
# 1. Name to app id (5 credits)
curl "https://www.socialcrawl.dev/v1/app_store/app-search?query=photo%20editor&country=US" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. The full record for one app (5 credits)
curl "https://www.socialcrawl.dev/v1/app_store/app-info?app_id=324684580" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 3. What its users say (5 credits)
curl "https://www.socialcrawl.dev/v1/app_store/app-reviews?app_id=324684580&sort_by=most_helpful&depth=200" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Finding apps [#finding-apps]

`app-search` returns keyword matches with title, icon, rating, price or free flag and store URL.
`depth` defaults to 100 and rounds up to multiples of 100, capped at 300.

`/v1/app_store/app-listings-search` is the deeper alternative and the only App Store endpoint
with real pagination. It searches a listings database by `title`, optionally narrowed by
`description` text, and returns a total count across the whole store alongside the page. `limit`
runs 1-50, `offset` up to 10,000, and `offset_token` carries you past that. It also accepts a
DataForSEO `filters` expression as a JSON array. It costs 10 credits, which is the price of
being able to enumerate rather than sample.

`/v1/app_store/search-suggestions` returns the autocomplete hints Apple offers for a partial
keyword, each with its rank in Apple's own ordering, for 1 credit. 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 [#app-detail-and-reviews]

`app-info` returns the record search results leave out: description, developer, rating, price,
version, minimum iOS version, size, screenshots and age advisories.

`app-reviews` returns user reviews with star rating, title, full text, reviewer name and publish
date. They 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 [#charts]

`app-list` returns a store chart by name. `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`, and `app_category` scopes any of them to one
category. `depth` runs up to 500.

```bash
# Top free iPhone photo apps in Korea
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: $SOCIALCRAWL_API_KEY"
```

Taxonomy endpoints [#taxonomy-endpoints]

Three 1-credit endpoints describe what the others accept, and are worth calling once and
caching. `/v1/app_store/categories` lists the values `app_category` takes on `app-list`.
`/v1/app_store/locations` lists the supported storefronts with their numeric location codes.
`/v1/app_store/languages` lists the supported language codes.

Endpoints [#endpoints]

<PlatformEndpoints platform="app_store" />

Read this before you build [#read-this-before-you-build]

**`country` accepts three shapes.** An ISO code (`US`), a full country name (`United States`),
or a numeric location code (`2840`) all work, and it defaults to the US. Get the numeric codes
from `locations`.

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

**Reviews are capped at 600.** No parameter raises that ceiling — it is what Apple exposes
publicly. If you need a longer history, sample repeatedly over time rather than trying to page
past it.

**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.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `app-search`, `app-info`, `app-reviews` and `app-list` are 5 credits; `app-listings-search` is
  10; the suggestion and taxonomy endpoints are 1
* `language` defaults to `en` everywhere and does not change which storefront is queried