Android SDK

You can obtain the source and example programs at https://github.com/audiogum/androidsdk.

class AudiogumClient

Methods

Constuctor

Initialise the SDK with client key and secret

public AudiogumClient(String key, String secret, String deviceId)
public AudiogumClient(String key, String secret, String deviceId, AudiogumConfiguration configuration)

Parameters

  • key client key issued by Audiogum
  • secret client secret issued by Audiogum
  • deviceId unique device identifier
  • configuration configuration options to be used in this instance (optional)

Constuctor

Initialise the SDK with access token

public AudiogumClient(AccessToken accessToken, String deviceId)
public AudiogumClient(AccessToken accessToken, String deviceId, AudiogumConfiguration configuration)

Parameters

  • accessToken access token issued by Audiogum API
  • deviceId unique device identifier
  • configuration configuration options to be used in this instance

IP Address Lookup

IP address lookup based upon client IP address. This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com

Requires signin scope.

public Single<IpLookup> getIpMap()

Returns

  • Single IpLookup result

Get Client Configuration

Gets country-specific configuration including both service configuration such as which content services are supported, and custom configuration settings for the client.

Requires signin scope.

public Single<AppConfig> getConfig()

Returns

  • Single AppConfig

Add User Config

Allows upload of arbitrary user config key/value pairs to store settings.

Requires write_userprofile scope.

public Single<Map<String, String>> updateUserConfig(Map< String, String > userConfig)

Parameters

  • userConfig oem-specific user config

Returns

  • Single<Map<String, String>>> Map of key value config

Update User Config by Key

Add or update user config by key

Requires write_userprofile scope.

public Single<Map<String, String>> updateUserConfigByKey(String key, Map<String, String> value)

Parameters

  • key config key
  • value config value

Returns

  • Single<Map<String, String>> Map of key value config

Delete User Config by Key

Delete user config by key

Requires write_userprofile scope.

public Completable deleteUserConfigByKey(String key)

Parameters

  • key key to delete

Returns

  • Completable result

Get User Config

Gets previously stored key/value pairs.

Requires read_userprofile scope.

public Single<Map<String, String>> getUserConfig()

Returns

  • Single<String, String> Map of key value config

Get User Config by Key

Get user config by key

Requires read_userprofile scope.

public Single<Map<String, String>> getUserConfigByKey(String key)

Parameters

  • key config key

Result

  • Single <String, String> Map of key value config

Add User Image

Allows upload of a Base64 encoded JPG or PNG image with maximum size 800px x 800px. Once in place, an imageuri property will be added to the user account.

Requires write_userprofile scope.

public Single<UserImage> updateUserImage(UserImageimage)

Parameters

  • image image to add

Returns

  • Single image

Delete User Image

Delete user image

Requires write_userprofile scope.

public Completable deleteUserImage()

Returns

  • Completable

Update User Profile Image

Add or update user profile image

Requires write_userprofile scope.

public Single<UserImage> updateUserProfileImage(String userProfileId, UserImage image)

Parameters

  • image image to add
  • userProfileId User Profile ID

Returns

  • Single image

Delete user profile image

Remove user profile image

Requires write_userprofile scope.

public Completable deleteUserProfileImage(String userProfileId)

Parameters

  • userProfileId User Profile ID

Returns

  • Completable

Reset User Password

Native client user email reset - sends a password reset email

public Completable resetUserPassword(String email)

Parameters

  • email email address

Returns

  • Completable

Login User

Login a user and set AccessToken

public Completable loginUser(String email, String password, String scope)

Parameters

  • email email address
  • password password
  • scope scope

Returns

  • Completable

Login External User

Login a user and set AccessToken

public Completable loginExternalUser(String externalUserId)
public Completable loginExternalUser(String externalUserId, String countryCode)
public Completable loginExternalUser(String externalUserId, String countryCode, String scope)

Parameters

  • externalUserId external UserId
  • countryCode country code
  • scope scope

Returns

Completable

Login Mobile User

Login a mobile user and set AccessToken

public Completable loginMobileUser(String mobileNumber, String code)
public Completable loginMobileUser(String mobileNumber, String code, String scope)

Parameters

  • mobileNumber mobile number
  • code verification code
  • scope scope

Returns

Completable

Logout User

Logs the user out of the API, clearing any cached data present.

public void logoutUser()

Is User Logged In?

Is a user logged in?

public Boolean isUserLoggedIn()

Returns

True if user logged in

Create User

Regiser a new user. Assumes password been confirmed on client

public Completable createUser(String email, String password) 
public Completable createUser(String firstName, String lastName, String email, String password)

Parameters

  • firstName first name
  • lastName last name
  • email email address
  • password password

Returns

  • Completable

Get User Account Details

Get user account details by userid Gets the full account details.

Requires read_userprofile scope.

public Single<UserInfo> getUser()

Returns

  • Single user info

Update User Account Details

If currentpassword or newpassword are passed both are required otherwise any non-password field can be submitted optionally. If email is included for update, this will not be updated immediately but a verification email will be sent. Once the verification link is clicked, the email will update.

Requires write_userprofile scope.

public Single<UserInfo> updateUser(UserInfo userInfo)

Parameters

  • userInfo user info

Returns

  • Single> user profiles

Get User Profiles

Get user profiles

Requires read_userprofile scope.

public Single<List<UserProfile>> getUserProfiles()

Returns

  • Single updated user profile

Update User Profile

Add or updates user profile

Requires write_userprofile scope.

public Single<UserProfile> updateUserProfile(String firstname, String lastname)

Parameters

  • firstname first name
  • lastname last name

Returns

  • Single updated user profile

Update User Profile By Id

Update user profile details

Requires write_userprofile scope.

public Single<UserProfile> updateUserProfileById(String firstname, String lastname, String userProfileId)

Parameters

  • firstname first name
  • lastname last name
  • userProfileId User Profile ID

Returns

  • Single updated user profile

Get User Profile By Id

Get user profile details

Requires read_userprofile scope.

public Single<UserProfile> getUserProfileById(String userProfileId)

Parameters

  • userProfileId User Profile ID

Returns

  • Completable

Delete User Profile By Id

Delete a user profile

Requires write_userprofile scope.

public Completable deleteUserProfileById(String userProfileId)

Parameters

  • userProfileId User Profile ID

Returns

  • Completable

Verify User Mobile

Native client verification - verifies a user's mobile number

public Completable verifyUserMobile(String mobileNumber, String code)

Parameters

  • mobileNumber mobile number
  • code verification code

Returns

  • Completable

Verify User Email

Native client verification - sends a verification email

public Completable verifyUserEmail(String email)

Parameters

  • email email address

Returns

  • Completable

Check User Exists

Check if an account exists Check if an account exists by email address

public Completable checkUserExists(String email)
public Completable checkUserExists(String email, Boolean validate)

Parameters

  • email The Email address to look up
  • validate Flag to enable email address validation

Returns

  • Completable

Get Support Documentation

Get help and support content Requires signin scope.

public Single<SupportDocumentation> getSupportDocumentation(String lang)

Parameters

  • lang Language code to look for; falls back to en

Returns

  • Single support documentation

Send Support Email

Sends support email

Requires signin scope.

public Completable sendSupportEmail(SupportEmail supportEmail)

Parameters

  • supportEmail email to send

Returns

  • Completable

Start Service Authorization

Gets an authorize URI to start a OAuth2 flow with the content service.

Requires write_userprofile scope.

public Single<UserServiceAuthorizeDetails> startServiceAuthorization(String serviceId)

Parameters

  • serviceId the id of the service.

Returns

  • Single UserServiceAuthorizeDetails, including authorize URI

Obtain Service Token

Obtain or refresh a service access token

Requires write_userprofile scope.

public Single<UserServiceCredentials> obtainServiceToken(String serviceId, String code)

Parameters

  • serviceId the id of the service.
  • code Optional OAuth2 authorization code from the service

Returns

Single details of the service credentials

Remove Service Token

Remove a service access token

Requires write_userprofile scope.

public Completable removeserviceToken(String serviceId)

Parameters

  • serviceId the id of the service.

Returns

Completable

Browse Service

Browse service content. Returns a list of items of type category; which can be explored with the ultimate goal of drilling down to items of types such as internetradio, audiobook or playlist. To explore a category, pass it's ref to this API in the parent parameter. Some services will return nested items within the category meaning no callback is required to explore further.

Requires search scope.

public Single<SearchResultsGroup> browseService(String service)
public Single<SearchResultsGroup> browseService(String service, Long children)
public Single<SearchResultsGroup> browseService(String service, String parent)
public Single<SearchResultsGroup> browseService(String service, String parent, Long startindex)
public Single<SearchResultsGroup> browseService(String service, String parent, Long startindex, Long itemsperpage)
public Single<SearchResultsGroup> browseService(String service, String parent, Long startindex, Long itemsperpage, Long children)

Parameters

  • service The content service
  • parent Optional parent group for drill down
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return in each bucket - defaults to 20
  • children Optionally 'peek' into categories and include this number of child items in each category - defaults to 0 (no child item peeking), maximum 5

Returns

  • Single content

Get Artist

Get an artist by id Get an artist by id. Returns artisttype, biogs, dateofbirth, dateofdeath, gender, genres, images, links, name, origin, originname, popularity, related, similar, services, tags, territory, yearsactive.

Requires search scope.

public Single<Artist> getArtist(String artistId)

Parameters

  • artistId Artist id

Returns

  • Single artist details

Get Artist Songs

Gets an artist's songs from a service based on our id

Requires search scope.

public Single<TrackListing> getArtistSongs(String artistId, String service) 
public Single<TrackListing> getArtistSongs(String artistId, String service, Long startindex)
public Single<TrackListing> getArtistSongs(String artistId, String service, Long startindex, Long itemsperpage)

Parameters

  • artistId Audiogum artist id
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • Single songs

Get Artist Songs By Ref

Get an artists songs from a service based on its ref

Requires search scope.

public Single<TrackListing> getArtistSongsByRef(String service, String ref)
public Single<TrackListing> getArtistSongsByRef(String service, String ref, Long startindex)
public Single<TrackListing> getArtistSongsByRef(String service, String ref, Long startindex, Long itemsperpage)

Parameters

  • ref The content service reference
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • Single songs

Get Artist Albums

Gets an artist's albums from a service based on our id

Requires search scope.

public Single<PlaylistListing> getArtistAlbums(String artistId, String service)
public Single<PlaylistListing> getArtistAlbums(String artistId, String service, Long startindex)
public Single<PlaylistListing> getArtistAlbums(String artistId, String service, Long startindex, Long itemsperpage)

Parameters

  • artistId Audiogum artist id
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • Single albums

Get Artist Albums By Ref

Gets an artist's albums from a service based on its ref

Requires search scope.

public Single<PlaylistListing> getArtistAlbumsByRef(String service, String ref)
public Single<PlaylistListing> getArtistAlbumsByRef(String service, String ref, Long startindex)
public Single<PlaylistListing> getArtistAlbumsByRef(String service, String ref, Long startindex, Long itemsperpage)

Parameters

  • ref The content service reference
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • Single albums

Get Artist Albums By Ref

Gets an artist's albums from a service based on its ref

Requires search scope.

public Single<SearchResultsGroup> getArtistAlbumsByRef(String service, String ref, String itemtype)
public Single<SearchResultsGroup> getArtistAlbumsByRef(String service, String ref, String itemtype, Long startindex)
public Single<SearchResultsGroup> getArtistAlbumsByRef(String service, String ref, String itemtype, Long startindex, Long itemsperpage)

Parameters

  • ref The content service reference
  • service The content service
  • itemtype The type of item to fetch. See ThirdPartyServiceConfig.drilldowntypes in getAppConfig response for valid types for each service.
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • Single results

Search across content services for content. Returns search results in various buckets

  • e.g. Playlists, Radio Stations, Artists.

Requires search scope.

public Single<SearchResults> search(String text)
public Single<SearchResults> search(String text, Long itemsperpage)
public Single<SearchResults> search(String text, Long itemsperpage, List<String> type)
public Single<SearchResults> search(String text, Long itemsperpage, List<String> type, List<String> service)

Parameters

  • text Content query
  • itemsperpage Number of items in each bucket - default 3
  • type Optional filter parameter that limits types searched to those that are in this comma delimited list
  • service Optional filter parameter that limits the services searched to those that are in this list (assuming they are allowed for the user)

Returns

Single search results

Get Album Tracks

Get tracks for an album

Requires search scope.

public void getAlbumTracks(String service, String ref, Callback<TrackListing> callback)

Parameters

  • service The content service
  • ref Service reference of parent

Returns

  • Single tracks

Get Album Tracks

Get tracks for an album

Requires search scope.

public Single<TrackListing> getAlbumTracks(String service, String ref)
public Single<TrackListing> getAlbumTracks(String service, String ref, Long startindex, Long itemsperpage)

Parameters

  • service The content service
  • ref Service reference of parent

Returns

  • Single tracks

Get Playlist Tracks

Get tracks for a playlist

Requires search scope.

public Single<TrackListing> getPlaylistTracks(String service, String ref)
public Single<TrackListing> getPlaylistTracks(String service, String ref, Long startindex, Long itemsperpage)

Parameters

  • service The content service
  • ref Service reference of parent
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • Single tracks

Get Songs by Parent

Gets songs of a parent item - e.g. songs for an album, playlist. See https://www.audiogum.com/developers/docs/contentaggregation#drill_down.

Requires search scope.

public Single<TrackListing> getSongsByParent(String type, String service, String ref)
public Single<TrackListing> getSongsByParent(String type, String service, String ref, Long itemsperpage)
public Single<TrackListing> getSongsByParent(String type, String service, String ref, Long itemsperpage, Long startindex)

Parameters

  • type The resource type
  • service The content service
  • ref The content service resource reference
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • Single tracks

Get Service Song

Gets a song by service reference.

Requires search scope.

public Single<Track> getServiceSong(final String ref, final String service)
public Single<Track> getServiceSong(final String ref, final String service, final Long itemsperpage)
public Single<Track> getServiceSong(final String ref, final String service, final Long itemsperpage, final Long startindex)

Parameters

  • ref The content service resource reference
  • service The content service
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • Single song

Get Service Playlist

Gets a playlist or album by service reference.

Requires search scope.

public Single<Playlist> getServicePlaylist(final String type, final String ref, final String service)
public Single<Playlist> getServicePlaylist(final String type, final String ref, final String service, final Long itemsperpage)
public Single<Playlist> getServicePlaylist(final String type, final String ref, final String service, final Long itemsperpage, final Long startindex)

Parameters

  • type The resource type ("playlist" or "album")
  • ref The content service resource reference
  • service The content service
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • Single playlist

Search Artists

Search artists

Requires search scope.

public Single<SearchResultsGroup> searchArtist(String text)
public Single<SearchResultsGroup> searchArtist(String text, Long itemsperpage, Long startindex)

Parameters

  • text Query to search for
  • itemsperpage Number of items in each bucket - default 20
  • startindex Page start position - default 0

Returns

  • Single results

Search Artists By Ids

Search artists

Requires search scope.

public Single<SearchResultsGroup> searchArtistByIds(List<String> id)
public Single<SearchResultsGroup> searchArtistByIds(List<String> id, Long itemsperpage, Long startindex)

Parameters

  • id IDs to obtain details for
  • itemsperpage Number of items in each bucket - default 20
  • startindex Page start position - default 0

Returns

  • Single results

Search By Type and Service

Single bucket results for paging Drill down into detailed results for paging through a bucket.

Requires search scope.

public Single<SearchResultsGroup> searchByTypeService(String type, String service, String text)
public Single<SearchResultsGroup> searchByTypeService(String type, String service, String text, Long itemsperpage, Long startindex)

Parameters

  • type The bucket type
  • service The content service
  • text Content query
  • itemsperpage Number of items in each bucket - default 20
  • startindex Page start position - default 0

Returns

  • Single results

Get Genres

Get a list of genres. Includes popularity in the current country and localized name.

Requires search scope.

public Single<Genres> getGenres()
public Single<Genres> getGenres(Long itemsperpage, Long startindex)

Parameters

  • startindex Paging - the offset that items should start at
  • itemsperpage Paging - the number of items to return

Returns

  • Single genres

Get top Artists for Genres

Get the top artists (by popularity) for a selection of given genres

Requires search scope.

public Single<TopArtistsByGenre> getTopArtistsForGenre(List<String> genre)
public Single<TopArtistsByGenre> getTopArtistsForGenre(List<String> genre, Long itemsperpage, Long startindex)
public Single<TopArtistsByGenre> getTopArtistsForGenre(List<String> genre, List<String> fields)
public Single<TopArtistsByGenre> getTopArtistsForGenre(List<String> genre, List<String> fields, Long itemsperpage, Long startindex)

Parameters

  • genre The genres to get topartists for
  • startindex Paging - the offset that items should start at
  • itemsperpage Paging - the number of items to return
  • fields The fields to return

Returns

  • Single top artists by genre

Get Top Artists

The most popular artists across a range of genres, merged together.

Requires search scope.

public Single<TopArtists> getTopArtists()
public Single<TopArtists> getTopArtists(List<String> fields, Long itemsperpage)

Parameters

  • itemsperpage Paging - the number of items to return
  • fields The fields to return

Returns

  • Single top artists

Get User Services

Get details of content services currently linked to the user.

Requires read_userprofile scope.

public Single<List<Service>> getUserServices()

Returns

  • Single> containing linked services.

Get User Service

Get details of a single content service currently linked to the user.

Requires read_userprofile scope.

public Single<Service> getUserService(String serviceId)

Parameters

  • serviceId the id of the service.

Returns

  • Single containing service details, if available.

Create User Playable

Request to create a playable and associate it with a device, based on specified parameters. This will update an existing playable if it exists for the same user with the same parameters.

For examples, see https://www.audiogum.com/partners/docs/playback.html

Requires write_playlists scope.

public Single<Playable> createUserPlayable(CreatePlayableRequestrequest)

Parameters

  • request Information required to create a user playable

Returns

  • Single playable

Get Playable Tracks

Get information for a playable for playback based on its id. Depending on the type of playable, this gives a list of items or a streamurl for playback, plus data for service authentication where necessary.

For examples, see https://www.audiogum.com/partners/docs/playback.html

Requires read_playlists scope.

public Single<PlayableTracks> getPlayableTracks(String id)
public Single<PlayableTracks> getPlayableTracks(String id, Boolean streamurls)
public Single<PlayableTracks> getPlayableTracks(String id, Boolean streamurls, Long startindex)
public Single<PlayableTracks> getPlayableTracks(String id, Boolean streamurls, Long startindex, Long itemsperpage)

Parameters

  • id playable id
  • streamurls Optionally omit stream urls (false). Default (true) indicates include where applicable
  • startindex Optional start index within the playlist. Omit this to use automatic continuation.
  • itemsperpage Optional number of items to get. Omit this to accept the default which may vary by playable type and service.

Returns

Single playableTracks

Delete Playable

Deletes a specific playable based on its id

Requires write_playlists scope.

public Completable deletePlayable(String id)

Parameters

  • id playable id

Returns

Completable

Get User Playable

Get the details including items of a specific playable based on its id (note: this is not for playback purposes)

Requires read_playlists scope.

public Single<PlayableTracks> getUserPlayableItems(String id, Long startindex)
public Single<PlayableTracks> getUserPlayableItems(String id, Long startindex, Long itemsperpage)

Parameters

  • id playable id
  • startindex Optional start index within the playlist. Omit this to use automatic continuation.
  • itemsperpage Optional number of items to get. Omit this to accept the default which may vary by playable type and service.

Returns

Single playableTracks

Get User Playables

List the playables created by the user. By default this gives results in order of most recently used.

Requires read_playlists scope.

public Single<Playables> getUserPlayables()
public Single<Playables> getUserPlayables(String type)
public Single<Playables> getUserPlayables(String type, String service)
public Single<Playables> getUserPlayables(String type, String service, String deviceId)
public Single<Playables> getUserPlayables(String type, String service, String deviceId, Long startindex)
public Single<Playables> getUserPlayables(String type, String service, String deviceId, Long startindex, Long itemsperpage)

Parameters

  • type Optionally filter by type of playable
  • service Optionally filter by service provider
  • deviceId Optionally filter by device
  • startindex Start index for paging (default 0)
  • itemsperpage Number of results per page (default 10)

Returns

Single playables

Refresh Stream Urls

Refresh streaming urls on behalf of the user for specific items from a service, for the case of time-limited content

Requires read_playlists scope.

public Single<TrackListing> refreshStreamUrls(String id, String service, List<String> trackids)

Parameters

  • id playable id
  • service service provider
  • trackids track ids to refresh

Returns

Single updated tracks

Get Remote Control Supported Acions

Get remotecontrol details of connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

public Single<RemoteControlSupportedActionsDetails> getRemoteControlDetails(String remoteControlToken)

Parameters

  • remoteControlToken Remote control token

Returns

  • Single details

Get Remote Control Device Player details

Get player state from a connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

public Single<DevicePlayerDetails> getRemoteControlDevicePlayerDetails(String remoteControlToken)

Parameters

  • remoteControlToken Remote control token

Returns

  • Single details

Get Remote Control Device details

Get device state from a connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

public Single<RemoteControlDeviceDetails> getRemoteControlDeviceDetails(String remoteControlToken)

Parameters

  • remoteControlToken Remote control token

Returns

  • Single details

Get Remote Control Device Preset details

Get preset state from a connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

public Single<RemoteControlDevicePresetDetails> getRemoteControlDevicePresetsDetails(String remoteControlToken)

Parameters

  • remoteControlToken Remote control token

Returns

  • Single details

Authenticate For Voice

Authenticates the user, creating a 'speech' scoped token and a token valid for use in the remote control websockets API.

Call this method early in your flow if you know you will need voice capabilities, as opening the first voice session without first calling this method can be slow and lead to a poor user experience.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.

public Completable authenticateForVoice()

Returns

  • Completable

Open Voice Session

Starts a voice session. This allows the client to talk to the Audiogum Voice service which are APIs for controlling devices through voice commands. This method must be called before any data is sent to the voice service through sendVoiceMessage(String message) or sendVoiceMessage(byte[] message).

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.

public Completable openVoiceSession(VoiceProperties voiceProperties, VoiceListener voiceListener)

Parameters

  • voiceProperties The voiceproperties to initiate a voice interaction.
  • voiceListener A listener that will receive to messages sent back from the voice service. It may also be sent again during the interaction as necessary to update nowplaying data if the player state changes.

Returns

  • Completable

Send Voice Message

Send a string message to the voice service.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.

public void sendVoiceMessage(String message)

Parameters

  • message The message

Send Binary Voice Message

Send a binary message to the voice service.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.

public void sendVoiceMessage(byte[] message)

Parameters

  • message The message

Send Voice Terminator

Sends an empty (zero byte) binary message to the service to indicate that no more bytes are expected.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.

public void sendVoiceTerminator()

Close Voice Session

Closes any active voice session.

public void closeVoiceSession()

Generate Response Audio

public Single<Respond> generateResponseAudio(String phraseKey, String languageCode)`

Generates an audio response for the specified phrase in the language desired.

Requires speech scope.

Parameters

  • phraseKey the key of the phrase to generate audio for.
  • languageCode the language to use when generating. If null, the user's language will be used.

Returns

A response to be used for this phrase.

Get Speech Suggestions

public Single<SpeechSuggestionResponse> getSpeechSuggestions()
public Single<SpeechSuggestionResponse> getSpeechSuggestions(SpeechSuggestionRequest request)

Get (possibly personalised) example phrases that can be used to describe how speech control works

Requires speech scope.

Parameters

  • request now playing data and language code

Returns

Speech suggestions

Make Speech Request with Action Text

public Single<TextToActionResponse> makeSpeechRequestWithActionText(TextToActionRequest request)

Convert the text of an instruction into the action that should be performed.

Requires speech scope.

Parameters

  • request speech text and language code

Returns

Action to be performed.

Send Analytics Events

public Completable sendAnalyticsEvents(Event[] events, boolean validateonly)

Send user and client behaviour analytics events.

Requires write_events scope.

See https://www.audiogum.com/developers/docs/analytics for more detail.

Parameters

  • events The events to be recorded.
  • validateonly if true, events will be validated only and not processed.

Returns

Completable

Upload Log

public Completable uploadLog(String deviceId, String logType, String logContent) throws IOException

Upload a log or crash dump file.

Requires write_device scope.

Parameters

  • deviceId The id of the device the log relates to.
  • logType The type of log to be sent.
  • logContent The content to be logged.

Returns

Completable

Get Taste Profile

public Single<TasteProfile> getTasteProfile()

Gets the user's full taste profile.

Requires read_userprofile scope.

Returns

Single The user's full taste profile.

Add Likes To Taste Profile

public Completable addLikesToTasteProfile(Artist[] artists)
public Completable addLikesToTasteProfile(InternetRadio[] internetRadios)
public Completable addLikesToTasteProfile(Playlist[] playlists, Playlist[] albums)
public Completable addLikesToTasteProfile(Track[] songs)
public Completable addLikesToTasteProfile(Artist[] artists, InternetRadio[] internetRadios, Playlist[] playlists, Playlist[] albums, Track[] songs)

Adds likes to a user's taste profile.

Requires write_userprofile scope.

Parameters

  • artists Artists to be added to the profile.
  • internetRadio Internet Radio stations to be added to the profile.
  • playlists Playlists to be added to the profile.
  • albums Albums to be added to the profile.
  • songs Songs to be added to the profile

Returns

Completable

Add To Taste Profile

public Completable addToTasteProfile(TasteProfile tasteProfile)

Adds Items to a user's taste profile.

Requires write_userprofile scope.

Parameters

  • items Items to be added to the profile.

Returns

Completable

Delete Likes From Taste Profile

public Completable deleteLikesFromTasteProfile(Artist[] artists)
public Completable deleteLikesFromTasteProfile(InternetRadio[] internetRadios)
public Completable deleteLikesFromTasteProfile(Playlist[] playlists, Playlist[] albums)
public Completable deleteLikesFromTasteProfile(Track[] songs)
public Completable deleteLikesFromTasteProfile(Artist[] artists, InternetRadio[] internetRadio, Playlist[] playlists, Playlist[] albums, Track[] songs)

Removes likes from a user's taste profile.

Requires write_userprofile scope.

Parameters

  • artists Artists to be removed from the profile.
  • internetRadio Internet radio stations to be removed from the profile.
  • playlists Playlists to be removed from the profile.
  • albums Albums to be removed from the profile.
  • songs Songs to be removed from the profile.

Returns

Completable

Delete From Taste Profile

public Completable deleteFromTasteProfile(TasteProfile tasteProfile)

Removes items from a user's taste profile.

Requires write_userprofile scope.

Parameters

  • tasteProfile Items to be removed from the profile.

Returns

Completable

Get Taste Genre Tags

public Single<TagsProfile> getTasteGenreTags()
public Single<TagsProfile> getTasteGenreTags(Integer tagsPerItem)

Gets the top genre tags in the user's profile. Each result indicates the number of liked items in the user's taste, and the percentage of liked items that match the tag.

Requires read_userprofile scope.

Parameters

  • tagsPerItem Optionally limit the tag values used per item to the specified number of most important values

Returns

Single A TagsProfile containing the user's top genre tags.

Check Taste State by Name

public Single<TasteMatch> checkArtistTasteStateByName(String name)

Check state of item in taste profile by name

Requires read_userprofile scope.

Parameters

  • name The name to match

Returns

Single the taste match information for this name

Add to Taste Profile by Name

public Completable addToTasteProfileByName(TasteProfile itemsToAdd)

Add items to the taste profile by name

Requires read_userprofile scope.

Parameters

  • name item to be added

Returns

Completable

Browse Tagonomy Nodes

public Single<TagonomyResult> browseTagonomy(String id)
public Single<TagonomyResult> browseTagonomy(String id, String service)
public Single<TagonomyResult> browseTagonomy(String id, String service, Long startindex)
public Single<TagonomyResult> browseTagonomy(String id, String service, Long startindex, Long itemsperpage)

Browse artists by tag node network. For a given node returns some artists satisfying the associated tags, and related nodes to explore.

Requires search scope

Parameters

  • id id of tag node in browse network. Omit to see root nodes.
  • service Specify a 3rd party music service (required if needing to filter artists for availability)
  • startindex Offset that artists should start at (paging)
  • itemsperpage Number of artists to return (paging)

Returns

TagonomyResult containing artists and related nodes.

Get User Contexts

public Single<UserContexts> getUserContexts()

Get all contexts including user configuration

Returns

UserContexts all UserContexts or configuration for unset contexts

Get User Context By Id

public Single<UserContext> getUserContext(final String contextid)

Get a context including user configuration if any

Parameters

  • contextid context id

Returns

UserContext or configuration

Update User Context

public  Single<UserContext> updateUserContext(final String contextid, final UserContext userContext)

Sets (enables, configures) a context for the user

Parameters

  • contextid context id
  • userContext context

Returns

Updated UserContext

Get Matching User Context

public Single<UserContext> getUserContext(Double latitude, Double longitude, Date datetime)
public Single<UserContext> getUserContext(Double latitude, Double longitude, String activity, Date datetime)

Get the current matching context if any given user's current state

Parameters

  • latitude Latitude of current location
  • longitude Longitude of current location
  • activity Current activity
  • datetime Datetime

Returns

Matching UserContext

Get Context Matches

public Single<UserContextMatches> getContextMatches(Double latitude, Double longitude, String activity, Date datetime)

Evaluates the conditions for every enabled context to explain matching

Parameters

  • latitude Latitude of current location
  • longitude Longitude of current location
  • activity Current activity
  • datetime Datetime

Returns

Matched, unmatched contexts and reasons for every enabled context

Get App Release

public Single<AppRelease> getAppRelease(@NonNull String region, @NonNull String platform, @NonNull String appstore,
                                        @NonNull String version, String language, String altapp,
                                        String platformversion, String devicemanufacturer, String devicename)

Fetches details of any available app update.

Parameters

  • region Region to check for (required)
  • platform Operating system (required)
  • appstore App Store to check (required)
  • version Current version installed (required)
  • language Get releasenotes in this language
  • altapp Codename of alternative app. Omit this for releases of the default app.
  • platformversion Optional operating system version
  • devicemanufacturer Optional device manufacturer
  • devicename Optional device name

Returns

an AppRelease describing the available update, or null if none available.

Register Device

public Completable registerDevice()

Registers the device making the SDK calls with the Audiogum API. This is required to ensure your analytics data is as accurate as possible.

Returns

Completable

Get User Devices

public Single<DeviceList> getUserDevices(String[] deviceTypes)

Lists the devices this user has been associated with.

Parameters

  • deviceTypes An optional array of device types to fetch.

Returns

a DeviceList containing information about the devices associated to the current user.

Get User Owned Devices

public Single<DeviceList> getUserOwnedDevices()

Lists the devices currently owned by the current user. Note that the full device info is not shown here.

Returns

a DeviceList containing information about the user's currently owned devices.

Register User Owned Device

public Completable registerUserOwnedDevice(@NonNull String deviceid)

Creates an ownership relationship betweenn the specified device and the current user. If the device already has a different owner, this request will fail with 409 response code.

Parameters

  • deviceid the id of the device being marked as owned.

Returns

Completable