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

{
  "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

{
  "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

{
  "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:

{
  "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

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

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

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:

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:

{
  "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 for Apple Music page and catalog workflows
• Apple App Store Scraper for deeper app-specific metadata
• Apple App Store Reviews Scraper for public app review records
• 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.