Skip to main content
MusicCatalogService provides idempotent, cacheable read access to songs, albums, and artists. It’s the workhorse of any music client.

​
Operations

RPCWhat it does
GetSongFetch a song by SongID.
BatchGetSongsUp to N songs in one call — returns a map of ID → song-or-error.
GetAlbumFetch an album by AlbumID.
GetAlbumTracksPaginated tracks of an album.
BatchGetAlbumsBatch albums.
GetArtistFetch an artist by ArtistID.
GetArtistDiscographyAlbums by an artist (filter by album type, paginated).
GetArtistTopTracksMost popular songs by an artist.
GetRelatedArtistsSimilar artists.
BatchGetArtistsBatch artists.
GetLyricsTime-synchronized lyrics when available, plain text otherwise.
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 (use LibraryService for that).

​
Batch vs single

When you need more than ~3 entities of the same kind, prefer BatchGet*:
  • 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.
const res = await music.batchGetSongs({
  songIdList: ["123", "456", "789"].map(value => ({ value })),
});
for (const [id, result] of Object.entries(res.results)) {
  if (result.song) console.log(id, result.song.title);
  else console.warn(id, result.error?.code);
}

​
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 include Cache-Control hints. Treat artwork URLs as immutable for the lifetime of the entity (artwork rotation creates a new URL).

​
Markets

Some endpoints accept a market parameter (e.g. GetArtistTopTracks) to scope popularity to a specific country. Omit for global.