# App Store API guide



## Start with App Store



Find an iOS app in a chosen storefront, read its listing and collect available reviews from the same country. App Store track IDs differ from Android package names.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Find an app



Save the selected listing’s id as the app_id for later requests, along with its storefront. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/app_store/app-search)



**app_store/app-search**

```
curl "https://www.monocrawl.com/v1/app_store/app-search?query=spotify&country=gb" \
  -H "x-api-key: mn_your_key_here"
```



### 2. Read the listing



Replace the example app_id with the selected result. Listing ratings belong to the selected storefront and source snapshot. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/app_store/app-info)



**app_store/app-info**

```
curl "https://www.monocrawl.com/v1/app_store/app-info?app_id=324684580&country=gb" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Read reviews



Use that numeric app_id. Review depth requests work; it does not guarantee every requested page has results. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/app_store/app-reviews)



**app_store/app-reviews**

```
curl "https://www.monocrawl.com/v1/app_store/app-reviews?app_id=324684580&country=gb&depth=1&sort_by=mostrecent" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Identifiers and markets | Listing lookup accepts a numeric track ID or bundle ID; reviews require a numeric track ID. Keep the selected country across the workflow. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/app_store/app-info) |
| Review filters | depth requests up to five source pages of up to 50 reviews. Availability can stop earlier. rating is filtered locally after collection; a sparse result does not prove few matching reviews exist. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/app_store/app-reviews) |
| Unsupported controls | The charts source does not support app_category or language filters; these are reported in warnings and ignored. The reviews source also does not support language filtering. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/app_store/app-list) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| Top free or paid apps | [`app-list`](https://www.monocrawl.com/docs/endpoints/app_store/app-list) | Choose app_collection; inspect warnings for unsupported chart filters. |
| Valid storefronts | [`locations`](https://www.monocrawl.com/docs/endpoints/app_store/locations) | Read reference values before selecting a country. |
| Category identifiers | [`categories`](https://www.monocrawl.com/docs/endpoints/app_store/categories) | Use the returned IDs; do not reuse Google Play category names. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Other operations



- [`app-info`](https://www.monocrawl.com/docs/endpoints/app_store/app-info)

- [`app-list`](https://www.monocrawl.com/docs/endpoints/app_store/app-list)

- [`languages`](https://www.monocrawl.com/docs/endpoints/app_store/languages)

- [`locations`](https://www.monocrawl.com/docs/endpoints/app_store/locations)



### Reviews and offers



- [`app-reviews`](https://www.monocrawl.com/docs/endpoints/app_store/app-reviews)



### Search and discovery



- [`app-search`](https://www.monocrawl.com/docs/endpoints/app_store/app-search)

- [`search-suggestions`](https://www.monocrawl.com/docs/endpoints/app_store/search-suggestions)



### Products and categories



- [`categories`](https://www.monocrawl.com/docs/endpoints/app_store/categories)



## Endpoint reference

## app_store/app-info

`GET /v1/app_store/app-info`

Full App Store app record: description, price, ratings, genres, screenshots, current version, release notes and size. similar_apps and more_apps_by_developer are filled only when the answering source supplies them (related_apps_included says which); the official store lookup does not carry them.

*App Store app details*

| Parameter | Required | Description |
| --- | --- | --- |
| `app_id` | yes | Numeric App Store track id, or a bundle id like com.spotify.client — e.g. `324684580` |
| `country` | no | 2-letter storefront country code (default us) — e.g. `us` |
| `language` | no | Result language code (e.g. en_us, ja_jp) — e.g. `en_us` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/app_store/app-info?app_id=324684580" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "123456789",
  "name": "Example App",
  "bundle_id": "com.example.app",
  "price": {
    "amount": 0,
    "currency": "GBP",
    "free": true
  },
  "rating": {
    "average": 4.5,
    "count": 100
  }
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/app-info#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/app-info.json)


## app_store/app-list

`GET /v1/app_store/app-list`

Apple Marketing Tools top-free / top-paid app chart for a storefront, ranked.

*App Store top charts*

| Parameter | Required | Description |
| --- | --- | --- |
| `app_collection` | yes | Chart collection. top-free and top-paid use the public charts feed; other collections require eligible alternate coverage. Accepted values: top-free, top-paid, topfreeapplications, toppaidapplications, top-grossing, new, new-free, new-paid. Case, spaces, hyphens and underscores are interchangeable. — e.g. `top-free` |
| `app_category` | no | Not supported by the Apple charts feed; acknowledged in _warnings and ignored — e.g. `6014` |
| `country` | no | 2-letter storefront country code (default us) — e.g. `us` |
| `language` | no | Not supported by the charts feed; acknowledged in _warnings and ignored — e.g. `en_us` |
| `depth` | no | Requested results, 1–100 (default 100); the source may return fewer. No per-item detail enrichment. — e.g. `100` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `depth`: Bound collection to the documented number of records or source pages. Depth semantics vary by endpoint and may affect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/app_store/app-list?app_collection=top-free" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [],
  "collection": "example",
  "count": 0,
  "country": "example",
  "items": [
    {
      "developer": {
        "name": "example"
      },
      "genres": [
        {}
      ],
      "icon_url": "https://example.com/example",
      "id": "example",
      "name": "example",
      "rank": 0,
      "release_date": "2026-09-01T12:00:00Z",
      "url": "https://example.com/example"
    }
  ],
  "updated_at": "2026-09-01T12:00:00Z"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/app-list#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/app-list.json)


## app_store/app-reviews

`GET /v1/app_store/app-reviews`

Retrieve App Store reviews in source pages of up to 50 reviews. Depth counts pages; rating filters apply locally after collection and do not guarantee a full page of matches.

*App Store app reviews*

| Parameter | Required | Description |
| --- | --- | --- |
| `app_id` | yes | Numeric App Store track id — e.g. `324684580` |
| `country` | no | 2-letter storefront country code (default us) — e.g. `us` |
| `language` | no | Not supported by the Apple reviews feed; acknowledged in _warnings and ignored — e.g. `en_us` |
| `depth` | no | Number of source pages, each containing up to 50 reviews; not a review count. Rating filters are applied locally to the retrieved pages and can return fewer or zero matches. — e.g. `1` |
| `sort_by` | no | mostrecent (default) or mosthelpful Accepted values: mostrecent, mosthelpful. Case, spaces, hyphens and underscores are interchangeable. — e.g. `mostrecent` |
| `rating` | no | 1-5; filter applied locally after fetch (noted in _warnings) — e.g. `5` |
| `cursor` | no | Return the previous response cursor unchanged. Keep app_id, country, language, depth, sort_by and rating unchanged. Recent reviews can continue through source page 10; mosthelpful is a single feed. Each request retains the normal price. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `depth`: Bound collection to the documented number of records or source pages. Depth semantics vary by endpoint and may affect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/app_store/app-reviews?app_id=324684580" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "app_id": "example",
  "count": 0,
  "country": "example",
  "cursor": null,
  "items": [
    {
      "app_version": "example",
      "author": {
        "name": "example",
        "url": "https://example.com/example"
      },
      "id": "example",
      "rating": 0,
      "text": "example",
      "title": "example",
      "updated_at": "2026-09-01T12:00:00Z",
      "votes": {
        "count": 0,
        "sum": 0
      }
    }
  ],
  "sort_by": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/app-reviews#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/app-reviews.json)


## app_store/app-search

`GET /v1/app_store/app-search`

Search Apple App Store apps by keyword — name, developer, price, rating and genre per hit.

*App Store app search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search keywords — e.g. `spotify` |
| `country` | no | 2-letter storefront country code (default us) — e.g. `us` |
| `language` | no | Result language code (e.g. en_us, ja_jp) — e.g. `en_us` |
| `depth` | no | Requested results, 1–100 (default 100); the source may return fewer. No per-item detail enrichment. — e.g. `100` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `depth`: Bound collection to the documented number of records or source pages. Depth semantics vary by endpoint and may affect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 3 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/app_store/app-search?query=spotify" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "123456789",
      "name": "Example App",
      "bundle_id": "com.example.app",
      "rating": {
        "average": 4.5,
        "count": 100
      }
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/app-search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/app-search.json)


## app_store/categories

`GET /v1/app_store/categories`

Reference list of Apple App Store genre ids (6xxx) and Games sub-genres (7xxx). Static, costs no credits.

*App Store categories*

| Parameter | Required | Description |
| --- | --- | --- |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/app_store/categories" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "items": [
    {
      "id": "example",
      "name": "example",
      "parent_id": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/categories#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/categories.json)


## app_store/languages

`GET /v1/app_store/languages`

Reference list of iTunes Search API language codes (lang parameter). Static, costs no credits.

*App Store languages*

| Parameter | Required | Description |
| --- | --- | --- |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/app_store/languages" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "items": [
    {
      "code": "example",
      "documented": false,
      "name": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/languages#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/languages.json)


## app_store/locations

`GET /v1/app_store/locations`

Reference list of Apple App Store storefront country codes. Static, costs no credits.

*App Store storefronts*

| Parameter | Required | Description |
| --- | --- | --- |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/app_store/locations" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "items": [
    {
      "code": "example",
      "name": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/locations#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/locations.json)


## app_store/search-suggestions

`GET /v1/app_store/search-suggestions`

The search terms the App Store suggests for a partial query, in the order the store ranks them.

*App Store search suggestions*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Partial search term — e.g. `spotify` |
| `country` | no | 2-letter storefront country code (default us) — e.g. `us` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/app_store/search-suggestions?query=spotify" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [],
  "count": 0,
  "country": "example",
  "items": [
    {
      "rank": 0,
      "term": "example"
    }
  ],
  "query": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/app_store/search-suggestions#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/app_store/search-suggestions.json)