MobileClient — Mobile API client

class MobileClient(username=None, device_id=None, *, locale='en_US', session=None, token=None, token_handler=<class 'google_music.token_handlers.FileTokenHandler'>, token_handler_kwargs=None)[source]

API wrapper class to access Google Music mobile client functionality.

>>> from google_music import MobileClient
>>> mc = MobileClient('username')

Note

Streaming requires a device_id from a valid, linked mobile device. The MobileClient instance’s device_id can be changed after instantiation, or a different device_id provided to stream or stream_url.

Parameters
  • username (str, Optional) – Your Google Music username. Used to store OAuth tokens for multiple accounts separately.

  • device_id (str, Optional) – A mobile device ID. Default: MAC address is used.

  • locale (str, Optional) – ICU locale used to localize some responses. This must be a locale supported by Android. Default: 'en_US'.

  • session (GoogleMusicSession, Optional) – A session compatible with GoogleMusicSession.

  • token (dict, Optional) – An OAuth token compatible with oauthlib.

  • token_handler (TokenHandler, Optional) – A token handler class compatible with TokenHandler for dumping and loading the OAuth token.

  • token_handler_kwargs (dict, Optional) – Keyword arguments to pass to the token_handler class. These become attributes on the class instance.

Properties

MobileClient.device_id

The mobile device ID of the MobileClient instance.

MobileClient.is_subscribed

The subscription status of the account linked to the MobileClient instance.

MobileClient.locale

The locale of the MobileClient instance.

Can be changed after instantiation.

ICU locale used to localize some responses. This must be a locale supported by Android.

MobileClient.tier

The subscription tier of the MobileClient instance.

Can be changed after instantiation.

aa if subscribed, fr if not.

Meta

MobileClient.config()[source]

Get a listing of mobile client configuration settings.

MobileClient.device_deauthorize(device)[source]

Deauthorize a registered device.

Parameters

device (dict) – A device dict as returned by devices.

MobileClient.device_set(device)[source]

Set device used by MobileClient instance.

Parameters

device (dict) – A device dict as returned by devices.

MobileClient.devices()[source]

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

Information

MobileClient.album(album_id, *, include_description=True, include_songs=True)[source]

Get information about an album.

Parameters
  • album_id (str) – An album ID. Album IDs start with a ‘B’.

  • include_description (bool, Optional) – Include description of the album in the returned dict.

  • include_songs (bool, Optional) – Include songs from the album in the returned dict. Default: True.

Returns

Album information.

Return type

dict

MobileClient.artist(artist_id, *, include_albums=True, num_related_artists=5, num_top_tracks=5)[source]

Get information about an artist.

Parameters
  • artist_id (str) – An artist ID. Artist IDs start with an ‘A’.

  • include_albums (bool, Optional) – Include albums by the artist in returned dict. Default: True.

  • num_related_artists (int, Optional) – Include up to given number of related artists in returned dict. Default: 5.

  • num_top_tracks (int, Optional) – Include up to given number of top tracks in returned dict. Default: 5.

Returns

Artist information.

Return type

dict

MobileClient.playlist(playlist_id, *, include_songs=False)[source]

Get information about a playlist.

Parameters
  • playlist_id (str) – A playlist ID.

  • include_songs (bool, Optional) – Include songs from the playlist in the returned dict. Default: False

Returns

Playlist information.

Return type

dict

MobileClient.playlist_song(playlist_song_id)[source]

Get information about a playlist song.

Note

This returns the playlist entry information only. For full song metadata, use song with the 'trackId' field.

Parameters

playlist_song_id (str) – A playlist song ID.

Returns

Playlist song information.

Return type

dict

MobileClient.podcast(podcast_series_id, *, max_episodes=50)[source]

Get information about a podcast series.

Parameters
  • podcast_series_id (str) – A podcast series ID.

  • max_episodes (int, Optional) – Include up to given number of episodes in returned dict. Default: 50

Returns

Podcast series information.

Return type

dict

MobileClient.podcast_episode(podcast_episode_id)[source]

Get information about a podcast_episode.

Parameters

podcast_episode_id (str) – A podcast episode ID.

Returns

Podcast episode information.

Return type

dict

MobileClient.song(song_id)[source]

Get information about a song.

Parameters

song_id (str) – A song ID.

Returns

Song information.

Return type

dict

MobileClient.station(station_id, *, num_songs=25, recently_played=None)[source]

Get information about a station.

Parameters
  • station_id (str) – A station ID. Use ‘IFL’ for I’m Feeling Lucky.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 25

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

Returns

Station information.

Return type

dict

Browse

MobileClient.browse_podcasts(podcast_genre_id='JZCpodcasttopchartall')[source]

Get the podcasts for a genre from the Podcasts browse tab.

Parameters

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

Returns

Podcast dicts.

Return type

list

MobileClient.browse_podcasts_genres()[source]

Get the genres from the Podcasts browse tab dropdown.

Returns

Genre groups that contain sub groups.

Return type

list

MobileClient.browse_stations(station_category_id)[source]

Get the stations for a category from Browse Stations.

Parameters

station_category_id (str) – A station category ID as found with browse_stations_categories.

Returns

Station dicts.

Return type

list

MobileClient.browse_stations_categories()[source]

Get the categories from Browse Stations.

Returns

Station categories that can contain subcategories.

Return type

list

Explore

MobileClient.explore_genres(parent_genre_id=None)[source]

Get a listing of song genres.

Parameters

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

Returns

Genre dicts.

Return type

list

MobileClient.explore_tabs(*, num_items=100, genre_id=None)[source]

Get a listing of explore tabs.

Parameters
  • num_items (int, Optional) – Number of items per tab to return. Default: 100

  • genre_id (genre_id, Optional) – Genre ID from explore_genres to explore. Default: None.

Returns

Explore tabs content.

Return type

dict

Listen Now

MobileClient.listen_now_dismissed_items()[source]

Get a listing of items dismissed from Listen Now tab.

MobileClient.listen_now_items()[source]

Get a listing of Listen Now items.

Note

This does not include situations; use the situations method instead.

Returns

With albums and stations keys of listen now items.

Return type

dict

MobileClient.situations(*, tz_offset=None)[source]

Get a listing of situations.

Parameters

tz_offset (int, Optional) – A timezone offset from UTC in seconds.

Playlists

MobileClient.playlist(playlist_id, *, include_songs=False)[source]

Get information about a playlist.

Parameters
  • playlist_id (str) – A playlist ID.

  • include_songs (bool, Optional) – Include songs from the playlist in the returned dict. Default: False

Returns

Playlist information.

Return type

dict

MobileClient.playlists(*, include_songs=False)[source]

Get a listing of library playlists.

Parameters

include_songs (bool, Optional) – Include songs in the returned playlist dicts. Default: False.

Returns

A list of playlist dicts.

Return type

list

MobileClient.playlists_iter(*, start_token=None, page_size=250)[source]

Get a paged iterator of library playlists.

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

  • page_size (int, Optional) – The maximum number of results per returned page. Max allowed is 49995. Default: 250

Yields

list – Playlist dicts.

MobileClient.playlist_create(name, description='', *, public=False, songs=None)[source]

Create a playlist.

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

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

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

  • songs (list, Optional) – A list of song dicts to add to the playlist.

Returns

Playlist information.

Return type

dict

MobileClient.playlist_delete(playlist)[source]

Delete a playlist.

Parameters

playlist (dict) – A playlist dict.

MobileClient.playlist_edit(playlist, *, name=None, description=None, public=None)[source]

Edit playlist(s).

Parameters
  • playlist (dict) – A playlist dict.

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

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

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

Returns

Playlist information.

Return type

dict

MobileClient.playlist_subscribe(playlist)[source]

Subscribe to a public playlist.

Parameters

playlist (dict) – A public playlist dict.

Returns

Playlist information.

Return type

dict

MobileClient.playlist_unsubscribe(playlist)[source]

Unsubscribe from a public playlist.

Parameters

playlist (dict) – A public playlist dict.

MobileClient.playlist_song(playlist_song_id)[source]

Get information about a playlist song.

Note

This returns the playlist entry information only. For full song metadata, use song with the 'trackId' field.

Parameters

playlist_song_id (str) – A playlist song ID.

Returns

Playlist song information.

Return type

dict

MobileClient.playlist_songs(playlist)[source]

Get a listing of songs from a playlist.

Paramters:

playlist (dict): A playlist dict.

Returns

Playlist song dicts.

Return type

list

MobileClient.playlist_songs_add(songs, playlist, *, after=None, before=None, index=None, position=None)[source]

Add songs to a playlist.

Note

  • Provide no optional arguments to add to end.

  • Provide playlist song dicts for after and/or before.

  • Provide a zero-based index.

  • Provide a one-based position.

Songs are inserted at given index or position. It’s also possible to add to the end by using len(songs) for index or len(songs) + 1 for position.

Parameters
  • songs (dict or list) – A song dict or a list of song dicts.

  • playlist (dict) – A playlist dict.

  • after (dict, Optional) – A playlist song dict songs will follow.

  • before (dict, Optional) – A playlist song dict songs will precede.

  • index (int, Optional) – The zero-based index position to insert songs.

  • position (int, Optional) – The one-based position to insert songs.

Returns

Playlist dict including songs.

Return type

dict

MobileClient.playlist_songs_delete(playlist_songs)[source]

Delete songs from playlist.

Parameters

playlist_songs (dict or list) – A playlist song dict or a list of playlist song dicts.

Returns

Playlist dict including songs.

Return type

dict

MobileClient.playlist_songs_move(playlist_songs, *, after=None, before=None, index=None, position=None)[source]

Move songs in a playlist.

Note

  • Provide no optional arguments to move to end.

  • Provide playlist song dicts for after and/or before.

  • Provide a zero-based index.

  • Provide a one-based position.

Songs are inserted at given index or position. It’s also possible to move to the end by using len(songs) for index or len(songs) + 1 for position.

Parameters
  • playlist_songs (list) – A list of playlist song dicts.

  • after (dict, Optional) – A playlist song dict songs will follow.

  • before (dict, Optional) – A playlist song dict songs will precede.

  • index (int, Optional) – The zero-based index position to insert songs.

  • position (int, Optional) – The one-based position to insert songs.

Returns

Playlist dict including songs.

Return type

dict

MobileClient.thumbs_up_songs(*, library=True, store=True)[source]

Get a listing of ‘Thumbs Up’ songs.

Parameters
  • library (bool, Optional) – Include ‘Thumbs Up’ songs from library. Default: True

  • generated (bool, Optional) – Include ‘Thumbs Up’ songs from store. Default: True

Returns

Dicts of ‘Thumbs Up’ songs.

Return type

list

Podcasts

MobileClient.podcast(podcast_series_id, *, max_episodes=50)[source]

Get information about a podcast series.

Parameters
  • podcast_series_id (str) – A podcast series ID.

  • max_episodes (int, Optional) – Include up to given number of episodes in returned dict. Default: 50

Returns

Podcast series information.

Return type

dict

MobileClient.podcasts(*, device_id=None)[source]

Get a listing of subsribed podcast series.

Paramaters:
device_id (str, Optional):

A mobile device ID. Default: Use device_id.

Returns

Podcast series dict.

Return type

list

MobileClient.podcasts_iter(*, device_id=None, page_size=250)[source]

Get a paged iterator of subscribed podcast series.

Parameters
  • device_id (str, Optional) – A mobile device ID. Default: Use device_id.

  • page_size (int, Optional) – The maximum number of results per returned page. Max allowed is 49995. Default: 250

Yields

list – Podcast series dicts.

MobileClient.podcast_episode(podcast_episode_id)[source]

Get information about a podcast_episode.

Parameters

podcast_episode_id (str) – A podcast episode ID.

Returns

Podcast episode information.

Return type

dict

MobileClient.podcast_episodes(*, device_id=None)[source]

Get a listing of podcast episodes for all subscribed podcasts.

Paramaters:
device_id (str, Optional): A mobile device ID.

Default: Use device_id of the MobileClient instance.

Returns

Podcast episode dicts.

Return type

list

MobileClient.podcast_episodes_iter(*, device_id=None, page_size=250)[source]

Get a paged iterator of podcast episode for all subscribed podcasts.

Parameters
  • device_id (str, Optional) – A mobile device ID. Default: Use device_id.

  • page_size (int, Optional) – The maximum number of results per returned page. Max allowed is 49995. Default: 250

Yields

list – Podcast episode dicts.

MobileClient.search(query, *, max_results=100, **kwargs)[source]

Search Google Music and library for content.

Parameters
  • query (str) – Search text.

  • max_results (int, Optional) – Maximum number of results per type per location to retrieve. I.e up to 100 Google and 100 library for a total of 200 for the default value. Google only accepts 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 returned dict. Setting none of them will include all result types in the returned dict.

Returns

A dict of results separated into keys:
  • 'albums'

  • 'artists'

  • 'genres'

  • 'playlists'

  • `'podcasts'

  • 'situations',

  • 'songs'

  • 'stations'

  • 'videos'

Return type

dict

Note

Free account search is restricted so may not contain hits for all result types.

MobileClient.search_google(query, *, max_results=100, **kwargs)[source]

Search Google Music for content.

Parameters
  • query (str) – Search text.

  • max_results (int, Optional) – Maximum number of results per type to retrieve. Google only accepts 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 returned dict. Setting none of them will include all result types in the returned dict.

Returns

A dict of results separated into keys:
  • albums

  • artists

  • genres

  • playlists

  • podcasts

  • situations

  • songs

  • stations

  • videos

Return type

dict

Note

Free account search is restricted so may not contain hits for all result types.

MobileClient.search_library(query, *, max_results=100, **kwargs)[source]

Search Google Music for content.

Parameters
  • query (str) – Search text.

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

  • kwargs (bool, Optional) –

    Any of:
    • 'playlists'

    • 'podcasts'

    • 'songs'

    • 'stations'

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

Returns

A dict of results separated into keys:
  • 'playlists'

  • 'podcasts'

  • 'songs'

  • 'stations'

Return type

dict

MobileClient.search_suggestion(query)[source]

Get search query suggestions for query.

Parameters

query (str) – Search text.

Returns

Suggested query strings.

Return type

list

Shuffle/Instant Mix

MobileClient.shuffle_album(album, *, num_songs=100, only_library=False, recently_played=None)[source]

Get a listing of album shuffle/mix songs.

Parameters
  • album (dict) – An album dict.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 100

  • only_library (bool, Optional) – Only return content from library. Default: False

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

Returns

List of album shuffle/mix songs.

Return type

list

MobileClient.shuffle_artist(artist, *, num_songs=100, only_library=False, recently_played=None, only_artist=False)[source]

Get a listing of artist shuffle/mix songs.

Parameters
  • artist (dict) – An artist dict.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 100

  • only_library (bool, Optional) – Only return content from library. Default: False

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

  • only_artist (bool, Optional) – If True, only return songs from the artist, else return songs from artist and related artists. Default: False

Returns

List of artist shuffle/mix songs.

Return type

list

MobileClient.shuffle_genre(genre, *, num_songs=100, only_library=False, recently_played=None)[source]

Get a listing of genre shuffle/mix songs.

Parameters
  • genre (dict) – A genre dict.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 100

  • only_library (bool, Optional) – Only return content from library. Default: False

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

Returns

List of genre shuffle/mix songs.

Return type

list

MobileClient.shuffle_song(song, *, num_songs=100, only_library=False, recently_played=None)[source]

Get a listing of song shuffle/mix songs.

Parameters
  • song (dict) – A song dict.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 100

  • only_library (bool, Optional) – Only return content from library. Default: False

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

Returns

List of artist shuffle/mix songs.

Return type

list

Songs

MobileClient.song(song_id)[source]

Get information about a song.

Parameters

song_id (str) – A song ID.

Returns

Song information.

Return type

dict

MobileClient.songs()[source]

Get a listing of library songs.

Returns

Song dicts.

Return type

list

MobileClient.songs_iter(*, page_size=250)[source]

Get a paged iterator of library songs.

Parameters

page_size (int, Optional) – The maximum number of results per returned page. Max allowed is 49995. Default: 250

Yields

list – Song dicts.

MobileClient.songs_add(songs)[source]

Add store songs to your library.

Parameters

songs (list) – A store song dict or a list of store song dicts.

Returns

Songs’ library IDs.

Return type

list

MobileClient.songs_delete(songs)[source]

Delete songs from library.

Parameters
  • songs (list) –

  • library song dict or a list of library song dicts. (A) –

Returns

Successfully deleted song IDs.

Return type

list

MobileClient.songs_play(songs)[source]

Add play to song play count.

Parameters

songs (dict or list) – A song dict or a list of song dicts.

Returns

True if successful, False if not.

Return type

bool

MobileClient.songs_rate(songs, rating)[source]

Rate song.

Parameters
  • songs (dict or list) – A song dict or a list of song dicts.

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

Returns

True if successful, False if not.

Return type

bool

MobileClient.thumbs_up_songs(*, library=True, store=True)[source]

Get a listing of ‘Thumbs Up’ songs.

Parameters
  • library (bool, Optional) – Include ‘Thumbs Up’ songs from library. Default: True

  • generated (bool, Optional) – Include ‘Thumbs Up’ songs from store. Default: True

Returns

Dicts of ‘Thumbs Up’ songs.

Return type

list

Stations

MobileClient.situations(*, tz_offset=None)[source]

Get a listing of situations.

Parameters

tz_offset (int, Optional) – A timezone offset from UTC in seconds.

MobileClient.station(station_id, *, num_songs=25, recently_played=None)[source]

Get information about a station.

Parameters
  • station_id (str) – A station ID. Use ‘IFL’ for I’m Feeling Lucky.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 25

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

Returns

Station information.

Return type

dict

MobileClient.stations(*, generated=True, library=True)[source]

Get a listing of library stations.

The listing can contain stations added to the library and generated from the library.

Parameters
  • generated (bool, Optional) – Include generated stations. Default: True

  • library (bool, Optional) – Include library stations. Default: True

Returns

Station information dicts.

Return type

list

MobileClient.stations_iter(*, page_size=250)[source]

Get a paged iterator of library stations.

Parameters

page_size (int, Optional) – The maximum number of results per returned page. Max allowed is 49995. Default: 250

Yields

list – Station dicts.

MobileClient.station_feed(*, num_songs=25, num_stations=4)[source]

Generate stations.

Note

A Google Music subscription is required.

Parameters
  • num_songs (int, Optional) – The total number of songs to return. Default: 25

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

Returns

Station information dicts.

Return type

list

MobileClient.station_songs(station, *, num_songs=25, recently_played=None)[source]

Get a listing of songs from a station.

Parameters
  • station (str) – A station dict.

  • num_songs (int, Optional) – The maximum number of songs to return from the station. Default: 25

  • recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where id is a song ID and type is 0 for a library song and 1 for a store song.

Returns

Station song dicts.

Return type

list

Stream

MobileClient.stream(item, *, device_id=None, quality='hi', session_token=None)[source]

Get MP3 stream of a podcast episode, library song, station_song, or store song.

Note

Streaming requires a device_id from a valid, linked mobile device.

Parameters
  • item (str) – A podcast episode, library song, station_song, or store song. A Google Music subscription is required to stream store songs.

  • device_id (str, Optional) – A mobile device ID. Default: Use device_id.

  • quality (str, Optional) –

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

    • 'med' (160Kbps)

    • 'low' (128Kbps)

    Default: 'hi'.

  • session_token (str, Optional) – Session token from a station dict required for unsubscribed users to stream a station song. station[‘sessionToken’] as returend by station only exists for free accounts.

Returns

An MP3 file.

Return type

bytes

MobileClient.stream_url(item, *, device_id=None, quality='hi', session_token=None)[source]

Get a URL to stream a podcast episode, library song, station_song, or store song.

Note

Streaming requires a device_id from a valid, linked mobile device.

Parameters
  • item (str) – A podcast episode, library song, station_song, or store song. A Google Music subscription is required to stream store songs.

  • device_id (str, Optional) – A mobile device ID. Default: Use device_id.

  • quality (str, Optional) –

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

    • 'med' (160Kbps)

    • 'low' (128Kbps)

    Default: 'hi'.

  • session_token (str) – Session token from a station dict required for unsubscribed users to stream a station song. station[‘sessionToken’] as returend by station only exists for free accounts.

Returns

A URL to an MP3 file.

Return type

str

Top Charts

MobileClient.top_charts()[source]

Get a listing of the default top charts.

MobileClient.top_charts_for_genre(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 with top_charts_genres.

MobileClient.top_charts_genres()[source]

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