# App Store Metadata & Charts (`timbered_oak/app-store-metadata-charts`) Actor

Apple App Store + Google Play app metadata lookup and Apple top-chart rank tracking. No reviews, no reviewer data.

- **URL**: https://apify.com/timbered\_oak/app-store-metadata-charts.md
- **Developed by:** [Mark](https://apify.com/timbered_oak) (community)
- **Categories:** SEO tools, Developer tools
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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 Metadata & Charts

Fetches app metadata from Apple's official `itunes.apple.com/lookup` and RSS
chart endpoints, and Google Play's public app page. No reviews, no reviewer
names — just app-level facts.

### Input

| Field | Type | Required | Notes |
|---|---|---|---|
| `mode` | `lookup` | `chart` | yes | `lookup` = metadata for specific apps. `chart` = a top chart (Apple only). |
| `platform` | `apple` | `play` | yes | `chart` mode only supports `apple` — Play has no public chart endpoint. |
| `appIds` | string\[] | for `lookup` | Apple numeric track ids (e.g. `284882215`) or Play package names (e.g. `com.facebook.katana`). |
| `country` | string | no | Two-letter store country code, default `us`. |
| `chart` | string | for `chart` | Apple RSS chart id, e.g. `topfreeapplications`, `toppaidapplications`, `topgrossingapplications`. Default `topfreeapplications`. |
| `limit` | integer | for `chart` | Number of chart rows to fetch. Default 25. |

### Output

One dataset row per app (`lookup`) or per chart position (`chart`).

**Apple lookup row** (real output, `id=284882215`):

```json
{
    "platform": "apple",
    "appId": "284882215",
    "bundleId": "com.facebook.Facebook",
    "title": "Facebook",
    "developer": "Meta Platforms, Inc.",
    "category": "Social Networking",
    "price": 0,
    "currency": "USD",
    "version": "576.0.0",
    "releaseNotes": "Our teams have solved many crashes, fixed issues you've reported and made the app faster.",
    "sizeBytes": "499631104",
    "ratingValue": 4.52536,
    "ratingCount": 28120782,
    "screenshotUrls": ["https://is1-ssl.mzstatic.com/..."],
    "country": "us",
    "fetchedAt": "2026-09-02T00:47:37.682Z"
}
```

**Apple chart row** (real output, `topfreeapplications`, US, rank 1):

```json
{
    "platform": "apple",
    "rank": 1,
    "country": "us",
    "chart": "topfreeapplications",
    "appId": "316126557",
    "bundleId": "com.aol.mapquest",
    "title": "MapQuest GPS Navigation & Maps",
    "developer": "MapQuest Holdings LLC",
    "category": "Navigation",
    "price": "Get",
    "date": "2026-09-02"
}
```

**Play lookup row** (real output, `com.facebook.katana`):

```json
{
    "platform": "play",
    "appId": "com.facebook.katana",
    "title": "Facebook",
    "developer": "Meta Platforms, Inc.",
    "category": "SOCIAL",
    "price": "0",
    "ratingValue": 4.559006690979004,
    "ratingCount": 185448370,
    "installsText": "10B+",
    "version": null,
    "jsonLd": { "...": "full schema.org SoftwareApplication block, when Play includes it" },
    "country": "us",
    "fetchedAt": "2026-09-02T00:47:28.497Z"
}
```

### Pricing

Pay-per-event:

- `app-scraped` — $0.00029 per app row (Apple or Play lookup).
- `rank-row` — $0.00085 per chart row.

Never charged on an empty result.

### Limits / known gaps

- **Play `version`** is not present in the static HTML since Google's page
  redesign (it now lives behind a JS-hydrated data blob we don't parse — that
  blob also contains individual review text/authors interleaved with app data,
  which we deliberately never touch). Field is always `null` for Play rows.
- **Play `installsText`** is the abbreviated label shown on the page (e.g.
  `"10B+"`), not an exact count — Play stopped publishing an exact number.
- **Play `jsonLd`** is `null` when Google omits the schema.org block for a
  given app/locale (observed present for major apps, not guaranteed for all).
- Apple `price` in chart rows is the store's own button label (`"Get"` for
  free, `"$X.XX"` for paid) rather than a normalized number — mirrors the RSS
  feed's own format.
- No proxy is used. Apple's endpoints are unthrottled JSON APIs; Play is a
  single unauthenticated page fetch per app. Very high volume against Play
  may eventually get rate-limited — no retry/backoff is implemented beyond
  what `got-scraping` does by default.

# Actor input Schema

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

lookup = fetch metadata for specific app ids/packages. chart = fetch a top chart (Apple only).

## `platform` (type: `string`):

apple = App Store. play = Google Play (lookup mode only).

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

For lookup mode: Apple numeric track ids (e.g. 284882215) or Play package names (e.g. com.facebook.katana).

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

Two-letter store country code.

## `chart` (type: `string`):

Apple RSS chart id for mode=chart, e.g. topfreeapplications, toppaidapplications, topgrossingapplications.

## `limit` (type: `integer`):

Number of chart rows to fetch (mode=chart).

## Actor input object example

```json
{
  "mode": "lookup",
  "platform": "apple",
  "appIds": [
    "284882215"
  ],
  "country": "us",
  "chart": "topfreeapplications",
  "limit": 10
}
```

# Actor output Schema

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

All scraped rows as JSON

# 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 = {
    "appIds": [
        "284882215"
    ],
    "country": "us",
    "chart": "topfreeapplications",
    "limit": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("timbered_oak/app-store-metadata-charts").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 = {
    "appIds": ["284882215"],
    "country": "us",
    "chart": "topfreeapplications",
    "limit": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("timbered_oak/app-store-metadata-charts").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 '{
  "appIds": [
    "284882215"
  ],
  "country": "us",
  "chart": "topfreeapplications",
  "limit": 10
}' |
apify call timbered_oak/app-store-metadata-charts --silent --output-dataset

```

## MCP server setup

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

```

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/vsIWybc1u7mRJ4cay/builds/rQxtPCNpDHHmfUUbZ/openapi.json