README

The iTunes Search API for omniscient/omnisong: a release with its tracks, their 30-second previews and its artwork, and an artist's albums - no key, through the application's HTTP client.

$itunes = (new ItunesCatalogFactory($http))->create(['country' => 'de']);   // $http: the application's HTTP client; none given, the factory makes its own

No framework needed: the package requires omniscient/omnisong and symfony/http-client. In a Symfony application, the same through the bundle's configuration:

omnisong:
    catalogs:
        itunes:
            factory: itunes
            options:
                country: 'de'                          # the store asked (default us)
                base_uri: 'https://itunes.apple.com/'

release() reads a UPC (lookup?upc=), an ISRC (lookup?isrc=, then the track's album), an Apple Music / iTunes URL (its album id) or the id itself (Reference::id(Platform::ITUNES, ...)), and answers with the title (the store's " - Single" / " - EP" read as the type), the artist, the label named by the ℗ line, the release date, the cover at 1200 px, the genre, and each track: title, number, disc, duration, previewUrl, its artist, its Apple Music URL. links() is the release's Apple Music link and the iTunes Store's; releases($artist) is search?entity=album&attribute=artistTerm, newest first, without the tracks.

What the API does not give: ISRCs and composers (both stay null), and any link outside Apple - those are omnisong/odesli's, which the aggregator asks by the id found here.

Unknown is null / an empty list; 403 and 429 (about 20 calls a minute are allowed) are a RateLimitedException; 5xx and a transport error an UnavailableException; any other 4xx a ProviderException. The previews are Apple's, for promotional use next to a link to the store: keep the Apple Music link beside the player.

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by Apple Inc. It reaches their service on behalf of whoever runs it, and it does not redistribute their data beyond the short excerpts recorded as test fixtures. Its MIT licence covers this package's code only and grants no right to the service or to its data.

Whoever installs and runs this package is responsible for complying with the iTunes Search API's terms (iTunes Search API terms), for obtaining whatever they require (an account, a key, a licence or subscription, an attribution or a citation, a rate limit to respect), and for any use made of what it returns. The authors publish it free of charge, make no commercial use of it, and accept no liability for how it is used (see LICENSE).

License: MIT since 2026-10-09; earlier versions remain published under LGPL-3.0-or-later.

omnisong / itunes

Package info

Security

Statistics

README

Responsibility