MusicCatalogService provides idempotent, cacheable read access to songs, albums, and artists. It’s the workhorse of any music client.
Operations
Full request/response schemas live in the API Reference under the
MusicCatalogService tag.
Authentication
All operations are accessible with either an API key or an OAuth access token. Catalog data is public — there is no user context needed unless you want to enrich responses with user-specific liked/saved state (useLibraryService for that).
Batch vs single
When you need more than ~3 entities of the same kind, preferBatchGet*:
- One request counts as one call against your rate limit, regardless of how many items you fetch.
- Items succeed and fail independently — the response is a map of ID →
{ song } | { error }. See Errors / Batch errors. - Network round-trip is a single TLS handshake instead of N.
Lyrics
GetLyrics returns either time-synchronized lyric lines (with millisecond timestamps suitable for karaoke-style highlighting) or plain text when sync data is unavailable. Branch on which oneof arm is populated.
Lyrics availability is rights-gated and varies by track and market.
Caching
All catalog reads are idempotent and may be cached client-side for up to your application’s tolerance — server responses includeCache-Control hints. Treat artwork URLs as immutable for the lifetime of the entity (artwork rotation creates a new URL).
Markets
Some endpoints accept amarket parameter (e.g. GetArtistTopTracks) to scope popularity to a specific country. Omit for global.
Related
- Music Search & Browse — full-text search and editorial browsing.
- Playlists — read playlists, including a user’s own.
- Library — liked songs, followed artists, history.
- Streaming & Billing — turning a
SongIDinto a playable stream URL.