`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.

Search¶

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.

MobileClient — Mobile API client¶

Properties¶

Meta¶

Information¶

Browse¶

Explore¶

Listen Now¶

Playlists¶

Podcasts¶

Search¶

Shuffle/Instant Mix¶

Songs¶

Stations¶

Stream¶

Top Charts¶

`MobileClient` — Mobile API client¶