Apple Music Track Downloader

Search the public iTunes Search API for Apple Music catalog metadata. The Actor returns normalized track, album, or artist records with public Apple Music links, artwork, prices, release information, and any public 30-second preview URL supplied by Apple.

No Apple Music login, subscription, API key, DRM circumvention, or full-track acquisition is used.

Features

• Search 1–50 validated, deduplicated terms in one run.
• Search the genuine public entities song, musicTrack, album, or musicArtist.
• Normalize the different public track, collection, and artist response shapes.
• Deduplicate records across queries using the country-qualified public catalog ID.
• Preserve the source API URL, source result count, and source result index for reproducibility.
• Retry transient API failures with bounded exponential backoff, a 15-second request timeout, and sequential pacing between queries.
• Generate 512px and 3000px artwork URLs from the public artwork URL already returned by Apple.

The public endpoint supports a maximum of 200 results per query. The Actor makes one bounded request per query because the public Search API response exposes limit but no verified offset/page parameter.

Input

Field	Type	Default	Required	Description
queries	array of strings	-	Yes	1–50 search terms of at most 200 characters each. Whitespace is normalized and case-insensitive duplicates are removed.
entity	string	song	No	One of song, musicTrack, album, or musicArtist.
country	string	us	No	Two-letter iTunes Store country code, for example us, gb, in, or fr.
maxTracksPerQuery	integer	10	No	Maximum public results requested per query, from 1 to 200.

Output

Each dataset row contains the existing normalized track fields plus stable public metadata when the selected entity provides it:

• Identity: recordType, id, trackId, albumId, artistId, entity, wrapperType.
• Names and catalog metadata: track/album/artist names, censored names, genre, genre ID, artist type, AMG artist ID, collection type, copyright, release date, track/disc numbers, and duration.
• Commercial and availability metadata: prices, currency, explicitness, and isStreamable.
• Public links and media: Apple Music/iTunes page URLs, artwork URLs, and previewUrl when Apple exposes a public 30-second AAC/M4A preview. Full-track URLs are not acquired or synthesized.
• Provenance: country, requestedCountry, searchQuery, sourceApi, source, sourceResultCount, sourceResultIndex, position, and scrapedAt.

Example input

{
  "queries": ["Example Artist Example Song", "Example Album"],
  "entity": "song",
  "country": "us",
  "maxTracksPerQuery": 10
}

Example output

{
  "position": 1,
  "recordType": "itunes_track",
  "id": "us:1234567891",
  "trackId": "1234567891",
  "trackName": "Example Song",
  "artistName": "Example Artist",
  "albumName": "Example Album",
  "genre": "Pop",
  "releaseDate": "2025-01-15T12:00:00.000Z",
  "durationMs": 210000,
  "durationFormatted": "3:30",
  "isExplicit": false,
  "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview000/example.preview.m4a",
  "artworkUrl512": "https://is1-ssl.mzstatic.com/image/thumb/Example/512x512bb.jpg",
  "trackViewUrl": "https://music.apple.com/us/album/example-album/1234567890?i=1234567891",
  "requestedCountry": "us",
  "searchQuery": "Example Artist Example Song",
  "source": "itunes-search-api",
  "scrapedAt": "2026-01-01T00:00:00.000Z"
}

Key-value store

The actor does not write custom key-value records. Apple Music metadata rows are stored in the dataset; the declared key-value store is intentionally empty.

Notes and boundaries

• Preview URLs are emitted only when the public API returns an HTTPS URL on Apple's public preview host.
• Artwork URLs are emitted only from Apple's public mzstatic.com artwork host. Larger artwork variants reuse the existing public size pattern.
• Search failures are logged and skipped per query; malformed results without a stable public ID are discarded. The run fails if no valid catalog records are produced.
• The Actor does not log in, use private Apple Music APIs, bypass access controls, download protected full tracks, or claim that a failed media request succeeded.