# App Store Scraper — App Details, Search & Top Charts (ASO) (`apricot_blackberry/app-store-scraper`) Actor

Know exactly where you and your competitors rank on the Apple App Store. One actor pulls live top charts, keyword search rankings, and full 44-field app details — straight off Apple's public APIs, no login, no tokens to break. Built for ASO, competitive intel, and AI agents.

- **URL**: https://apify.com/apricot\_blackberry/app-store-scraper.md
- **Developed by:** [Creator Fusion](https://apify.com/apricot_blackberry) (community)
- **Categories:** Developer tools, E-commerce, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 app details

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## App Store Scraper — App Details, Search & Top Charts (ASO)

**Know exactly where you and your competitors stand on the Apple App Store.** One actor, three modes, straight off Apple's public APIs — no login, no scraping tokens, no browser:

1. **Top charts** — the live Top Free / Paid / Grossing / New rankings, by category and country. Put it on a schedule and you've got a chart-movement time series most ASO tools charge hundreds a month for.
2. **Keyword search (ASO rankings)** — search any keyword and the result order *is* the ranking. Track where an app sits for the terms that matter, or discover every app competing for a keyword.
3. **App details** — 44 fields per app: ratings and rating counts (overall and current version), category, price, version, release + update dates, release notes, size, languages, content rating, description, icon, and every screenshot.

Built for ASO teams, app marketers, competitive-intelligence, and AI agents that need clean App Store data on demand.

### Quick start

Top-free chart (just press Start):

```json
{}
```

Keyword rankings:

```json
{ "searchTerms": ["meditation", "habit tracker"], "country": "us" }
```

App details:

```json
{ "appIds": ["324684580", "https://apps.apple.com/us/app/id389801252"] }
```

Games top-grossing chart in Japan:

```json
{ "chartType": "top-grossing", "genreId": "6014", "country": "jp" }
```

### Output (by rowType)

- **chart-entry**: `rank`, `chartType`, `country`, `appId`, `name`, `developer`, `category`, `price`, `icon`, `url`.
- **search-result**: `searchRank` (position for the term), `searchTerm`, plus the full app-detail fields below.
- **app**: `appId`, `bundleId`, `name`, `developer`, `rating`, `ratingCount`, `ratingCurrentVersion`, `primaryGenre`, `genres`, `price`, `version`, `releaseDate`, `currentVersionReleaseDate`, `releaseNotes`, `description`, `sizeBytes`, `minOsVersion`, `languages`, `contentRating`, `icon`, `screenshots`, `url`.
- **notice**: a friendly row explaining anything that didn't match — an unknown storefront, a not-found app, or a keyword with no results — so a run always returns something useful instead of just failing.

### Why this one

- **All-open, zero fragility** — pure Apple public APIs (iTunes lookup, search, and RSS charts). No reverse-engineered tokens to break, so runs don't silently die when Apple ships a change.
- **Both the "where do I rank" and "what's the app" questions** in one tool, instead of a separate single-purpose scraper for each.
- **Batch-efficient** — app details are fetched up to 200 ids per request; charts and search pull up to 200 in one call.
- **Self-healing** — direct first (free); on a rate-limit it retries through Apify residential proxy with a fresh rotating session before giving up, so proxy is billed only when needed.
- **Agent-ready** — typed rows with a `rowType` discriminator and a machine-readable SUMMARY in the key-value store.

### Integrations

Run it from anywhere — API, code, no-code automation, or an AI agent. Empty input returns the US top-free chart (never an error), so scheduled and speculative calls always get data.

**REST API (synchronous):**

```bash
curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~app-store-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["photo editor"],"country":"us"}'
```

**JavaScript (`apify-client`):**

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('apricot_blackberry/app-store-scraper').call({ appIds: ['324684580'] });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
const apps = items.filter((r) => r.rowType === 'app');
```

**Python (`apify-client`):**

```python
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("apricot_blackberry/app-store-scraper").call(run_input={"searchTerms": ["vpn"]})
rows = [r for r in client.dataset(run["defaultDatasetId"]).iterate_items()]
```

**AI agents (MCP):** the Actor is exposed through the Apify MCP server — point any MCP client (Claude, Cursor, etc.) at it:

```json
{ "mcpServers": { "apify": {
  "url": "https://mcp.apify.com/?tools=apricot_blackberry/app-store-scraper",
  "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" } } } }
```

**No-code:** use the official Apify app in **n8n, Make, and Zapier** and pick `app-store-scraper`. Configure an Apify **webhook** on run completion to push results into your pipeline without polling.

Every row carries a `rowType` discriminator (`chart-entry` / `search-result` / `app` / `notice`); a `notice` row explains anything that didn't match your input, and a machine-readable `SUMMARY` record lands in the key-value store.

### Honest limits

- **Reviews are not included.** Apple deprecated the public RSS review feed and gated the newer review endpoint behind rotating tokens; this actor sticks to the data that's reliably open (details, search, charts) rather than ship a review mode that breaks. If you need reviews, that's a separate, less stable surface.
- Charts and keyword search are capped at **200 results** per call by Apple.
- Rating counts and rankings are per **country store** — set `country` to the market you care about.

# Actor input Schema

## `mode` (type: `string`):

What to scrape. Auto-detected from your input: app ids/URLs → details; search terms → search; nothing → top charts.

## `searchTerms` (type: `array`):

Keywords to search the App Store for. Result order is the app's ranking for that keyword (ASO rank).

## `appIds` (type: `array`):

Numeric App Store app ids (e.g. 324684580) or full URLs (e.g. https://apps.apple.com/us/app/id324684580).

## `chartType` (type: `string`):

Which top chart to pull in charts mode.

## `genreId` (type: `string`):

Apple genre id to scope charts to a category (e.g. 6014 = Games, 6017 = Education, 6015 = Finance). Leave blank for all categories.

## `entity` (type: `string`):

What to search for in search mode.

## `country` (type: `string`):

Two-letter country code for the App Store storefront (e.g. us, gb, jp, cn, de).

## `maxItems` (type: `integer`):

Cap on rows per run (per chart, per search term, or total apps). Apple caps charts/search at 200.

## `delayBetweenRequests` (type: `integer`):

Pause between API calls.

## `navigationTimeoutMs` (type: `integer`):

Per-request timeout in milliseconds.

## `maxProxyRetries` (type: `integer`):

If a direct request fails or is rate-limited, retry through Apify residential proxy with a fresh rotating session, up to this many times, before giving up. 0 disables proxy fallback.

## `proxyConfiguration` (type: `object`):

Self-healing: requests go DIRECT first (free) against Apple’s public APIs, and only fall back to Apify residential proxy with a fresh rotating session if one fails — so you pay for proxy only when it’s actually needed. Set your own proxy here to override. Proxy data is billed to your Apify account.

## Actor input object example

```json
{
  "searchTerms": [],
  "appIds": [],
  "chartType": "top-free",
  "entity": "software",
  "country": "us",
  "maxItems": 50,
  "delayBetweenRequests": 300,
  "navigationTimeoutMs": 25000,
  "maxProxyRetries": 3
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [],
    "appIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("apricot_blackberry/app-store-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": [],
    "appIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("apricot_blackberry/app-store-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [],
  "appIds": []
}' |
apify call apricot_blackberry/app-store-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apricot_blackberry/app-store-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3LGt984brDFwhi3ka/builds/nuzIYbu5jl8hJh4Bn/openapi.json