# Apple iTunes Catalog Search & Lookup (`automation-lab/apple-itunes-search-lookup-metadata`) Actor

Search or look up Apple iTunes catalog records across apps, music, movies, podcasts, audiobooks, and ebooks; export normalized IDs, creators, genres, artwork, prices, release dates, and Store URLs.

- **URL**: https://apify.com/automation-lab/apple-itunes-search-lookup-metadata.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.47 / 1,000 item extracteds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Apple iTunes Catalog Search & Lookup

Search Apple's public iTunes catalog by term or resolve known catalog IDs into normalized metadata.

This Actor turns anonymous Apple iTunes Search API responses into consistent dataset rows across music, movies, podcasts, apps, audiobooks, ebooks, TV, music videos, and short films.

Use it to enrich a media catalog, validate identifiers, build research datasets, or take repeatable snapshots for change monitoring.

### What does this Actor do?

The Actor supports two complementary routes:

1. **Search** by one or more terms, a Store country, media type, entity, and optional search attribute.
2. **Lookup** one or many numeric Apple catalog IDs in batches.

Both routes return the same normalized output shape.

A single run can combine search and lookup inputs.

Duplicate entities are removed before they are saved or charged.

No Apple account, API key, browser, or proxy is required.

### Who is it for?

- Media-catalog teams enriching internal title and creator records
- App-intelligence analysts resolving App Store IDs
- Music researchers collecting album, song, and artist identity data
- Podcast teams finding shows and public RSS feed URLs
- Affiliate and content teams collecting canonical Apple Store URLs
- Data engineers normalizing mixed Apple media into one table
- Operators scheduling snapshots for downstream comparison

Choose this Actor when you need cross-media search and ID lookup.

For Apple Music page-specific extraction, use the related Apple Music Actor listed below.

### Why use Apple iTunes catalog metadata?

Apple's source fields differ by media family.

An app may have a bundle ID, version, rating, and seller.

A song may have an album, duration, track number, preview, and explicitness status.

A podcast may expose a public RSS feed.

This Actor maps those variations into stable columns while retaining entity-specific values where available.

Every row includes source provenance and a fetch timestamp.

### Supported media and entities

Search supports these Apple media families:

- `all`
- `music`
- `movie`
- `podcast`
- `software`
- `audiobook`
- `ebook`
- `musicVideo`
- `shortFilm`
- `tvShow`

Use `entity` for a more precise result type.

Common examples include `album`, `song`, `musicArtist`, `podcast`, `podcastEpisode`, `software`, `movie`, `audiobook`, and `ebook`.

Apple controls valid media/entity combinations.

Lookup works from numeric artist, collection, track, app, podcast, movie, or book IDs.

### Extracted data

| Field group | Example fields |
| --- | --- |
| Provenance | `sourceMode`, `sourceQuery`, `sourceUrl`, `fetchedAt` |
| Identity | `catalogId`, `artistId`, `collectionId`, `trackId`, `wrapperType`, `kind`, `mediaType` |
| Names | `title`, `creatorName`, `collectionName` |
| Classification | `genre`, `genres`, `explicitness` |
| Availability | `country`, `releaseDate`, `storeUrl` |
| Commerce | `price`, `formattedPrice`, `currency` |
| Media | `artworkUrl`, `previewUrl`, `feedUrl`, `durationMillis` |
| Sequence | `trackNumber`, `trackCount` |
| Apps | `bundleId`, `sellerName`, `version`, `minimumOsVersion`, `averageUserRating`, `userRatingCount` |
| Rights and copy | `copyright`, `description` |

Unavailable fields are returned as `null` or an empty genre array.

The Actor does not download artwork, audio, video, apps, or ebooks.

### Getting started

1. Open the Actor in Apify Console.
2. Add a value to **Search terms** or **Catalog IDs**.
3. Select the Store country.
4. For search, choose a media family and optional entity.
5. Set the global maximum output size.
6. Click **Start**.
7. Open the default dataset to view or export records.

The prefilled Radiohead search is a small working example.

### Input parameters

#### `searchTerms`

An array of up to 25 non-empty search strings.

Each term creates one Apple API request.

#### `catalogIds`

An array of up to 1,000 numeric IDs.

The Actor batches them into requests of at most 200 IDs.

#### `country`

A two-letter ISO country code such as `US`, `GB`, `DE`, or `JP`.

Country affects availability, currency, prices, and Store URLs.

#### `media`

The Apple media family used for search.

The default is `all`.

#### `entity`

An optional Apple entity name used to narrow search or expand a supported lookup.

Leave it empty to use Apple's default for the chosen media.

#### `attribute`

An optional search field such as `artistTerm`, `albumTerm`, `songTerm`, `titleTerm`, `authorTerm`, or `softwareDeveloper`.

#### `language`

Apple response language in `ll_CC` form.

The default is `en_us`.

#### `explicit`

Set to `No` to request results without explicit content.

#### `limitPerSearch`

Results requested per search term, from 1 to 200.

#### `maxItems`

Global saved-record cap after deduplication, from 1 to 5,000.

### Search example

```json
{
  "searchTerms": ["Radiohead"],
  "country": "US",
  "media": "music",
  "entity": "album",
  "limitPerSearch": 10,
  "maxItems": 10
}
```

This returns album identities, artist names, genres, artwork, prices, releases, and Apple Music URLs.

### Catalog ID lookup example

```json
{
  "catalogIds": ["284910350", "909253"],
  "country": "US",
  "maxItems": 10
}
```

The sample resolves a software record and an artist record through one lookup request.

IDs that Apple does not return do not create empty dataset rows and are not charged as records.

### Podcast monitoring example

```json
{
  "searchTerms": ["technology news", "artificial intelligence"],
  "country": "GB",
  "media": "podcast",
  "entity": "podcast",
  "limitPerSearch": 10,
  "maxItems": 20
}
```

Schedule this input and compare datasets between runs to identify additions or metadata changes.

The Actor produces snapshots; it does not send alerts or calculate diffs itself.

### Output example

A current music search produces a record shaped like this:

```json
{
  "sourceMode": "search",
  "sourceQuery": "Radiohead",
  "catalogId": "1109714933",
  "collectionId": 1109714933,
  "mediaType": "album",
  "title": "In Rainbows",
  "creatorName": "Radiohead",
  "collectionName": "In Rainbows",
  "genre": "Alternative",
  "releaseDate": "2007-12-28T08:00:00Z",
  "country": "USA",
  "currency": "USD",
  "price": 9.99,
  "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/.../100x100bb.jpg",
  "storeUrl": "https://music.apple.com/us/album/in-rainbows/1109714933?uo=4",
  "fetchedAt": "2025-01-15T12:00:00.000Z"
}
```

Additional schema fields remain available in exports even when they are not shown in the Console overview.

### How much does it cost to search the Apple iTunes catalog?

The Actor uses pay-per-event pricing.

A run currently has a **$0.005 start fee** plus a per-record charge.

On the BRONZE tier, each saved catalog record currently costs **$0.002452**.

| Useful records | BRONZE example total |
| ---: | ---: |
| 10 | $0.02952 |
| 100 | $0.2502 |
| 1,000 | $2.457 |

Only normalized records saved to the default dataset receive the item charge.

Duplicates, invalid response rows, and IDs omitted by Apple are not charged as records.

Apify plan tiers can have different per-record rates; Console shows the applicable rate before a run.

### Reliability and retries

The Actor calls Apple's public JSON API directly.

It retries transient network failures, timeouts, HTTP 429, and HTTP 5xx responses up to three attempts with backoff.

It does not blindly retry malformed input or deterministic API failures.

A persistent upstream failure makes the run fail with a non-zero status instead of returning a misleading empty success.

No residential proxy or browser fallback is enabled.

### Limits and source behavior

- Apple limits one search response to at most 200 records.
- The API does not provide search pagination beyond that response.
- Search ranking and catalog availability can differ by country and change over time.
- Some entity/media combinations are invalid and Apple may reject them.
- Lookup silently omits unknown or unavailable IDs.
- Field availability differs by media type.
- Artwork and preview URLs are owned and served by Apple or its media hosts.
- The Actor does not guarantee historical snapshots unless you schedule and retain runs.

### Export and integrations

Use Apify dataset export formats including JSON, CSV, Excel, XML, and RSS.

Common workflows include:

- Join `catalogId` to an internal media table.
- Resolve a batch of IDs before an affiliate-content refresh.
- Feed podcast `feedUrl` values into an RSS processing pipeline.
- Export software metadata for app-catalog checks.
- Schedule keyword searches and compare records by `catalogId`.
- Send datasets to Google Sheets, Make, Zapier, or a webhook integration.

### Run with the Apify API using cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~apple-itunes-search-lookup-metadata/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["Radiohead"],"country":"US","media":"music","entity":"album","maxItems":10}'
```

Poll the returned run or use Apify's synchronous dataset endpoint when appropriate.

Keep API tokens in environment variables or a secrets manager.

### Run with JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/apple-itunes-search-lookup-metadata').call({
  catalogIds: ['284910350', '909253'],
  country: 'US',
  maxItems: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Run with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/apple-itunes-search-lookup-metadata').call(run_input={
    'searchTerms': ['technology news'],
    'country': 'GB',
    'media': 'podcast',
    'entity': 'podcast',
    'maxItems': 10,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use through MCP

#### Claude Code setup

Add the Apify MCP server to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/apple-itunes-search-lookup-metadata"
```

#### Claude Desktop setup

Claude Desktop can use this JSON configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/apple-itunes-search-lookup-metadata"
    }
  }
}
```

#### Cursor setup

Add the same remote MCP URL in Cursor's MCP settings.

#### VS Code setup

Add the same remote MCP URL through the MCP server configuration supported by your VS Code client.

#### Example prompts

- "Search the US iTunes music catalog for Miles Davis albums and return IDs and release dates."
- "Look up these Apple catalog IDs and export title, creator, genre, price, and Store URL."
- "Find 20 UK artificial-intelligence podcasts and include RSS feed URLs."

### Legality and responsible use

Apple exposes the iTunes Search API publicly, but users remain responsible for their use of the data.

Review Apple's applicable terms, branding guidance, and content usage conditions.

Do not imply endorsement by Apple.

Do not republish copyrighted artwork, previews, descriptions, or media without the required rights.

Avoid collecting or combining data in ways that violate privacy, consumer-protection, or intellectual-property law.

This Actor is not affiliated with or endorsed by Apple Inc.

Apple, iTunes, Apple Music, App Store, and related marks belong to Apple Inc.

### Troubleshooting

#### The dataset is empty

Confirm that at least one search term or catalog ID is present.

Try the same ID on the intended Store country; unavailable IDs may be omitted by Apple.

Remove an overly restrictive entity or attribute and rerun a small test.

#### Apple returns an input error

Check that the country has two letters and catalog IDs contain digits only.

Verify the selected entity is valid for the selected media family.

#### Fewer results arrived than requested

Apple may return fewer matches than `limitPerSearch`.

Duplicates across terms are saved once.

The global `maxItems` cap can stop later requests early.

#### A field is null

Apple's response shape varies by entity.

For example, an artist does not necessarily have a track price, while software can expose app-specific rating and version fields.

### Related Automation Lab Actors

- [Apple Music Scraper](https://apify.com/automation-lab/apple-music-scraper) for Apple Music page and catalog workflows
- [Apple App Store Scraper](https://apify.com/automation-lab/apple-app-store-scraper) for deeper app-specific metadata
- [Apple App Store Reviews Scraper](https://apify.com/automation-lab/apple-app-store-reviews-scraper) for public app review records
- [Podcast Scraper](https://apify.com/automation-lab/podcast-scraper) for broader podcast discovery workflows

### FAQ

#### Does it need an Apple developer token?

No. It uses Apple's anonymous public iTunes Search and Lookup endpoints.

#### Can it search multiple countries in one run?

One run uses one country setting.

Create separate runs for separate Store countries so prices and availability remain unambiguous.

#### Can it download songs, artwork, apps, or books?

No. It exports metadata and source URLs only.

#### Can I look up different media types together?

Yes. A lookup batch can contain different numeric Apple catalog ID types.

#### Does it monitor changes automatically?

The Actor creates a current snapshot.

Use an Apify schedule and compare datasets or integrate a downstream diff step for monitoring.

#### Is every result guaranteed to have a canonical Store URL?

No. Most common catalog entities do, but Apple can omit fields for some result types.

#### Are no-match IDs charged as records?

No. Only useful normalized rows written to the dataset receive the item event charge.

# Actor input Schema

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

Terms to search in Apple's catalog. Each term produces a separate API search.

## `catalogIds` (type: `array`):

Numeric Apple iTunes or App Store artist, collection, track, podcast, book, movie, or software IDs to resolve.

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

Two-letter ISO country code controlling availability, prices, currency, and Store URLs.

## `media` (type: `string`):

Catalog media family used for search. Lookup requests resolve the supplied IDs independently of this field.

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

Optional Apple API entity such as album, song, musicArtist, podcast, podcastEpisode, software, movie, audiobook, or ebook. Leave empty for the media default.

## `attribute` (type: `string`):

Optional field to search, such as artistTerm, albumTerm, songTerm, titleTerm, authorTerm, or softwareDeveloper.

## `language` (type: `string`):

Language and country code in Apple's ll\_CC format.

## `explicit` (type: `string`):

Whether explicit catalog results may be returned by Apple.

## `limitPerSearch` (type: `integer`):

Maximum results requested from Apple for each search term (1–200).

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

Global cap across search and lookup results after deduplication.

## Actor input object example

```json
{
  "searchTerms": [
    "Radiohead"
  ],
  "country": "US",
  "media": "all",
  "language": "en_us",
  "explicit": "Yes",
  "limitPerSearch": 50,
  "maxItems": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing normalized Apple iTunes catalog records.

# 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": [
        "Radiohead"
    ],
    "country": "US",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/apple-itunes-search-lookup-metadata").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": ["Radiohead"],
    "country": "US",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/apple-itunes-search-lookup-metadata").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": [
    "Radiohead"
  ],
  "country": "US",
  "maxItems": 20
}' |
apify call automation-lab/apple-itunes-search-lookup-metadata --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/apple-itunes-search-lookup-metadata"
        }
    }
}

```

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/of7PrECuJOzKymfdg/builds/skqgDgOxX6H1AaYjf/openapi.json