mobileclient.calls — Mobile API call classes

Example of making an HTTP request using the requests library:

# Assuming an authenticated session named 'session'.
>>> from google_music_proto.mobileclient.calls import TrackFeed
>>> call = TrackFeed()
>>> response = session.request(
        call.method, call.url, params=call.params, headers=call.headers,
        data=call.body, allow_redirects=call.follow_redirects
    )

Attributes

Call class instances have the following attributes:

body

Binary-encoded body of the HTTP request.

follow_redirects

Boolean to enable/disable request redirects.

headers

Headers to send with the HTTP request.

method

Method for the HTTP request.

params

Dict of parameters to send in the query string of the HTTP request.

url

URL for the HTTP request.

Classes

class ActivityRecordRealtime(events_or_mutations)[source]

Record track play and rate events.

Use play to build track play event dicts. Use rate to build track rate events dicts.

Parameters

events (list or dict) – A list of event dicts or a single event dict.

endpoint

activity/recordrealtime

method

POST

static play(track_id, track_duration, *, play_time=None, stream_auth_id=None)[source]

Build a track play event.

Parameters
  • track_id (str) – A track ID.

  • track_duration (int or str) – The duration of the track.

  • play_time (int, Optional) – The amount of time user played the track in seconds. Default: track_duration

  • stream_auth_id (str, Optional) – The stream auth ID from a stream call’s headers.

Returns

An event dict.

Return type

dict

static rate(track_id, rating)[source]

Build a track rate event.

Parameters
  • track_id (str) – A track ID.

  • rating (int) – 0 (not rated), 1 (thumbs down), or 5 (thumbs up).

Returns

An event dict.

Return type

dict

class BrowseStationCategories[source]

Get a listing of station categories from the browse stations tab.

endpoint

browse/stationcategories

method

GET

schema

BrowseStationCategoriesSchema

class BrowseStations(station_category_id)[source]

Get a listing of stations by category from browse tab.

Parameters

station_category_id (str) – A station category ID as found in BrowseStationCategories response.

endpoint

browse/stations

method

GET

schema

BrowseStationsSchema

class BrowseTopChart[source]

Get a listing of the default top charts.

endpoint

browse/topchart

method

GET

schema

BrowseTopChartSchema

class BrowseTopChartForGenre(genre_id)[source]

Get a listing of top charts for a top chart genre.

Parameters

genre_id (str) – A top chart genre ID as found in BrowseTopChartGenres response.

endpoint

browse/topchartforgenres

method

GET

schema

BrowseTopChartSchema

class BrowseTopChartGenres[source]

Get a listing of genres from the browse top charts tab.

endpoint

browse/topchartgenres

method

GET

schema

BrowseTopChartGenresSchema

class Config[source]

Get a listing of mobile client configuration settings.

endpoint

config

method

GET

schema

ConfigListSchema

class DeviceManagementInfo[source]

Get a listing of devices registered to a Google Music account.

endpoint

devicemanagementinfo

method

GET

schema

UserClientIDListSchema

class DeviceManagementInfoDelete(device_id)[source]

Delete a registered device.

Parameters

device_id (str) – A device ID as found in DeviceManagementInfo response.

endpoint

devicemanagementinfo

method

DELETE

class EphemeralTop(max_results=1000, start_token=None, updated_min=None)[source]

Get a listing of ‘Thumbs Up’ store tracks.

Note

‘Thumbs Up’ library tracks are handled client-side. Use the TrackFeed call to find library tracks with a 'rating' of 5.

Note

The track list is paged. Getting all tracks will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Default: 1000

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds.

endpoint

ephemeral/top

method

POST

schema

EphemeralTopSchema

class ExploreGenres(parent_genre_id=None)[source]

Get a listing of track genres.

Parameters

parent_genre_id (str, Optional) – A genre ID. If given, a listing of this genre’s sub-genres is returned.

endpoint

explore/genres

method

GET

schema

GenreListSchema

class FetchAlbum(album_id, include_description=True, include_tracks=True)[source]

Get information about an album.

Parameters
  • album_id (str) – The album ID to look up.

  • include_description (bool, Optional) – Include description of the album in the response. Default: True

  • include_tracks (bool, Optional) – Include tracks from the album in the response. Default: True

endpoint

fetchalbum

method

GET

schema

AlbumSchema

class FetchArtist(artist_id, include_albums=True, num_related_artists=5, num_top_tracks=5)[source]

Get information about an artist.

Parameters
  • artist_id (str) – The artist ID to look up.

  • include_albums (bool, Optional) – Include albums from the artist in the response. Default: True

  • num_related_artists (int, Optional) – The maximum number of related artists to include in the response. Default: 5

  • num_top_tracks (int, Optional) – The maximum number of top tracks to include in the response. Default: 5

endpoint

fetchartist

method

GET

schema

ArtistSchema

class FetchTrack(track_id)[source]

Get information about a track.

Parameters

track_id (str) – A track ID to look up.

endpoint

fetchtrack

method

GET

schema

StoreTrackSchema

class IsPlaylistShared(playlist_id)[source]

Check if a playlist is shared.

Parameters

playlist_id (str) – A playlist ID.

endpoint

isplaylistshared

method

GET

schema

IsPlaylistSharedSchema

class ListenNowGetDismissedItems[source]

Get a listing of items dismissed from Listen Now tab.

endpoint

listennow/get_dismissed_items

method

GET

schema

ListenNowDismissedItemsSchema

class ListenNowGetListenNowItems[source]

Get a listing of Listen Now items.

Note

This does not include situations; use ListenNowSituations to get situations.

endpoint

listennow/getlistennowitems

method

GET

schema

ListenNowItemListSchema

class ListenNowSituations(tz_offset=None)[source]

Get a listing of Listen Now situations.

Parameters

tz_offset (int, Optional) – A time zone offset from UTC in seconds. Default is automatic detection.

endpoint

listennow/situations

method

POST

schema

ListenNowSituationListSchema

class PlaylistBatch(events_or_mutations)[source]

Create, delete, and edit playlists.

Use create to build playlist creation mutation dicts. Use delete to build playlist delete mutation dicts. Use edit to build playlist edit mutation dicts.

Parameters

mutations (list or dict) – A list of mutation dicts or a single mutation dict.

endpoint

playlistbatch

method

POST

static create(name, description, type_, *, owner_name=None, share_state=None, share_token=None)[source]

Build a playlist create event.

Parameters
  • name (str) – Name to give the playlist.

  • description (str) – Description to give the playlist.

  • type_ (str) – 'SHARED' if subscribing to a public playlist, 'USER_GENERATED' if creating a playlist.

  • share_state (str, Optional) – 'PUBLIC' to share the created playlist, 'PRIVATE' otherwise.

  • owner_name (str, Optional) – Owner name when susbcribing to a playlist.

  • share_token (str, Optional) – The share token of a shared playlist to subscribe to.

Returns

A mutation dict.

Return type

dict

static delete(playlist_id)[source]

Build a playlist delete event.

Parameters

playlist_id (str) – A playlist ID.

Returns

A mutation dict.

Return type

dict

static edit(playlist_id, name, description, share_state)[source]

Build a playlist edit event.

Parameters
  • playlist_id (str) – A playlist ID.

  • name (str) – Name to give the playlist.

  • description (str) – Description to give the playlist.

  • share_state (str) – 'PUBLIC' to share the playlist, 'PRIVATE' otherwise.

Returns

A mutation dict.

Return type

dict

class PlaylistEntriesBatch(events_or_mutations)[source]

Create, delete, and edit playlist entries.

Use create to build playlist entry creation mutation dicts. Use delete to build playlist entry delete mutation dicts. Use update to build playlist entry update mutation dicts.

Parameters

mutations (list or dict) – A list of mutation dicts or a single mutation dict.

endpoint

plentriesbatch

method

POST

static create(track_id, playlist_id, *, playlist_entry_id=None, preceding_entry_id=None, following_entry_id=None)[source]

Build a playlist entry create event.

Parameters
  • track_id (str) – A track ID.

  • playlist_id (str) – A playlist ID.

  • playlist_entry_id (str, Optional) – A playlist entry ID to assign to the created entry. Default: Automatically generated.

  • preceding_entry_id (str, Optional) – The playlist entry ID that should precede the added track. None if entry is to be in first position. Default: None

  • following_entry_id (str, Optional) – The playlist entry ID that should follow the added track. None if entry is to be in last position. Default: None

Returns

A mutation dict.

Return type

dict

static delete(playlist_entry_id)[source]

Build a playlist entry delete event.

Parameters

playlist_entry_id (str) – A playlist entry ID.

Returns

A mutation dict.

Return type

dict

static update(playlist_entry, *, preceding_entry_id=None, following_entry_id=None)[source]

Build a playlist entry update event.

Parameters
  • playlist_id (str) – A playlist ID.

  • preceding_entry_id (str, Optional) – The playlist entry ID that should precede the added track. None if entry is to be in first position. Default: None

  • following_entry_id (str, Optional) – The playlist entry ID that should follow the added track. None if entry is to be in last position. Default: None

Returns

A mutation dict.

Return type

dict

class PlaylistEntriesShared(share_tokens, max_results=250, start_token=None, updated_min=0)[source]

Get a listing of shared playlist entries.

Note

The shared playlist entries list is paged. Getting all shared playlist entries will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

plentries/shared

method

POST

schema

SharedPlaylistEntryListSchema

class PlaylistEntryFeed(max_results=250, start_token=None, updated_min=-1)[source]

Get a listing of user playlist entries.

Note

The playlist entry list is paged. Getting all playlist entries will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

plentryfeed

method

POST

schema

PlaylistEntryListSchema

class PlaylistFeed(max_results=250, start_token=None, updated_min=-1)[source]

Get a listing of library playlists.

Note

The playlist list is paged. Getting all playlists will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

playlistfeed

method

POST

schema

PlaylistListSchema

class Playlists[source]

Get a listing of library playlists.

endpoint

playlists

method

GET

schema

PlaylistListSchema

class PlaylistsCreate(name, description, public=False)[source]

Create a playlist.

Parameters
  • name (str) – Name to give the playlist.

  • description (str) – Description to give the playlist.

  • public (bool) – If True and account has a subscription, make playlist public. Default: False

endpoint

playlists

method

POST

schema

PlaylistSchema

class PlaylistsDelete(playlist_id)[source]

Delete a playlist.

Parameters

playlist_id (str) – A playlist ID.

endpoint

playlists

method

DELETE

class PlaylistsUpdate(playlist_id, name, description, public=False)[source]

Edit a playlist.

endpoint

playlists

method

PUT

schema

PlaylistSchema

class PodcastBrowse(podcast_genre_id='JZCpodcasttopchartall')[source]

Get a listing of podcasts from Podcasts browse tab.

Parameters

podcast_genre_id (str, Optional) – A podcast genre ID as found in PodcastBrowseHierarchy. Default: 'JZCpodcasttopchartall'

endpoint

podcast/browse

method

GET

schema

PodcastBrowseSchema

class PodcastBrowseHierarchy[source]

Get a listing of genres from Podcasts browse tab dropdown.

endpoint

podcast/browsehierarchy

method

GET

schema

PodcastBrowseHierarchySchema

class PodcastEpisode(device_id=None, max_results=250, start_token=None, updated_min=-1)[source]

Retrieve list of episodes from user-subscribed podcast series.

Note

The podcast episode list is paged. Getting all podcast episodes will require looping through all pages.

Parameters
  • device_id (str) – A mobile device ID.

  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

podcastepisode

method

GET

schema

PodcastEpisodeListSchema

class PodcastEpisodeStreamURL(podcast_episode_id, quality='hi', device_id=None)[source]

Get a URL to stream a podcast episode.

Parameters
  • podcast_episode_id (str) – A podcast episode ID.

  • device_id (str) – A mobile device ID.

  • quality (str, Optional) –

    Stream quality is one of:
    • 'hi' (320Kbps)

    • 'med' (160Kbps)

    • 'low' (128Kbps)

    Default: 'hi'

class PodcastFetchEpisode(podcast_episode_id)[source]

Get information about a podcast episode.

Parameters

podcast_episode_id (str) – A podcast episode ID to look up.

endpoint

podcast/fetchepisode

method

GET

schema

PodcastEpisodeSchema

class PodcastFetchSeries(podcast_series_id, max_episodes=50)[source]

Get information about a podcast series.

Parameters

podcast_series_id (str) – A podcast series ID to look up.

endpoint

podcast/fetchseries

method

GET

schema

PodcastSeriesSchema

class PodcastSeries(device_id=None, max_results=250, start_token=None, updated_min=-1)[source]

Retrieve list of user-subscribed podcast series.

Note

The podcast series list is paged. Getting all podcast series will require looping through all pages.

Parameters
  • device_id (str) – A mobile device ID.

  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

podcastseries

method

GET

schema

PodcastSeriesListSchema

class PodcastSeriesBatchMutate(events_or_mutations)[source]
endpoint

podcastseries/batchmutate

method

POST

class Query(query, *, max_results=100, **kwargs)[source]

Search Google Music.

Parameters
  • query (str) – Search text.

  • max_results (int, Optional) – Maximum number of results per type to retrieve. Google only acepts values up to 100. Default: 100

  • kwargs (bool, Optional) –

    Any of:
    • albums

    • artists

    • genres

    • playlists,

    • podcasts

    • situations

    • songs

    • stations

    • videos

    set to True will include that result type in the response. Setting none of them will include all result types in the response.

endpoint

query

method

GET

schema

SearchResponseSchema

class QuerySuggestion(query)[source]

Get a search suggestion.

Parameters

query (str) – Search text.

class RadioStation(max_results=250, start_token=None, updated_min=-1)[source]

Generate a listing of stations.

Note

The station list is paged. Getting all stations will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

radio/station

method

POST

schema

RadioListSchema

class RadioStationFeed(station_infos=None, num_entries=25, num_stations=4)[source]

Generate stations and get tracks from station(s).

Parameters
  • station_infos (list) –

    A list of station dicts containing keys:
    • 'station_id' or 'seed'

    • 'num_entries'

    • 'library_content_only'

    • 'recently_played'

    station_id is a station ID.

    'seed' is a dict containing a seed ID and seed type ('seedType'). See StationSeedType for seed type values.

    A seed ID can be:
    • artistId

    • albumId

    • genreId

    • trackId (store track)

    • trackLockerId (library track)

    num_entries is the maximum number of tracks to return from the station.

    library_content_only when True limits the station to library tracks. Default: False

    recently_played is a list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a track ID and type is 0 for a library track and 1 for a store track.

  • num_entries (int) – The total number of tracks to return. Default: 25

  • num_stations (int) – The number of stations to return when no station_infos is provided. Default: 4

endpoint

radio/stationfeed

method

POST

schema

RadioFeedSchema

class RadioStationTrackStreamURL(track_id, wentry_id, session_token, quality='hi', device_id=None)[source]

Get a URL to stream a station track with a free account.

Note

Subscribed accounts should use TrackStreamURL.

Unlike the other stream calls, this returns JSON with a ‘url’ key, not the location in headers.

Parameters
  • track_id (str) – A station track ID.

  • wentry_id (str) – The wentryid from a station track dict.

  • session_token (str) – The sessionToken from a RadioStationFeed response.

  • quality (str, Optional) –

    Stream quality is one of:
    • 'hi' (320Kbps)

    • 'med' (160Kbps)

    • 'low' (128Kbps)

    Default: 'hi'

  • device_id (str) – A mobile device ID.

class TrackBatch(events_or_mutations)[source]

Add, delete, and edit library tracks.

Note

This previously supported editing most metadata. It now only supports changing rating. However, changing the rating should be done with ActivityRecordRealtime and ActivityRecordRealtime.rate instead.

Use add to build track add mutation dicts. Use delete to build track delete mutation dicts. Use edit to build track edit mutation dicts.

Parameters

mutations (list or dict) – A list of mutation dicts or a single mutation dict.

endpoint

trackbatch

method

POST

schema

TrackBatchSchema

static add(store_track)[source]

Build a track add event.

Parameters

store_track (dict) – A store track dict.

Returns

A mutation dict.

Return type

dict

static delete(track_id)[source]

Build a track add event.

Parameters

track_id (str) – A track ID.

Returns

A mutation dict.

Return type

dict

static edit(track)[source]

Build a track edit event.

Parameters

track (dict) – A library track dict.

Returns

A mutation dict.

Return type

dict

class TrackFeed(max_results=250, start_token=None, updated_min=-1)[source]

Get a listing of library tracks.

Note

The track list is paged. Getting all tracks will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Default: 250

  • start_token (str, Optional) – The token of the page to return. Default: Not sent to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

trackfeed

method

POST

schema

TrackListSchema

class TrackStreamURL(track_id, quality='hi', device_id=None)[source]

Get a URL to stream a track.

Parameters
  • device_id (str) – A mobile device ID.

  • track_id (str) – A library or store track ID. A Google Music subscription is required to stream store tracks.

  • quality (str, Optional) –

    Stream quality is one of:
    • 'hi' (320Kbps)

    • 'med' (160Kbps)

    • 'low' (128Kbps)

    Default: 'hi'

class Tracks(max_results=1000, start_token=None, updated_min=-1)[source]

Get a listing of library tracks.

Note

The track list is paged. Getting all tracks will require looping through all pages.

Parameters
  • max_results (int, Optional) – The maximum number of results on returned page. Max allowed is 49995. Default: 1000

  • start_token (str, Optional) – The token of the page to return. Default: None to get first page.

  • updated_min (int, Optional) – List changes since the given Unix epoch time in microseconds. Default lists all changes.

endpoint

tracks

method

GET

schema

TrackListSchema