API 3 XML

Lets go through come calls and examples that you can do for each XML method.

Non-Data Methods

handshake

This is the function that handles verifying a new handshake Takes a timestamp, auth key, and username.

InputTypeDescriptionOptional
'auth'string$passphrase (Timestamp . Password SHA hash) OR (API Key)NO
'user'string$username (Required if login/password authentication)YES
'timestamp'integerUNIXTIME() (Timestamp used in seed of password hash. Required if login/password authentication)YES
'version'string$version (API Version that the application understands)YES

Example

ping

This can be called without being authenticated, it is useful for determining if what the status of the server is, and what version it is running/compatible with

InputTypeDescriptionOptional
'auth'string(Session ID) returns version information and extends the session if passedYES
'version'string$version (API Version that the application understands)YES

Example

url_to_song

This takes a url and returns the song object in question

InputTypeDescriptionOptional
'url'stringFull Ampache URL from server, translates back into a song XMLNO

Example

Data Methods

Changes to text searches

  • 'is not' has been added shifting values down the list. 0=contains, 1=does not contain, 2=starts with, 3=ends with 4=is, 5=is not, 6=sounds like, 7=does not sound like
  • rule_1['name'] is depreciated. Instead of rule_1['name'] use rule_1['title'] (I have put a temp workaround into the search rules to alleviate this change for any existing apps)

Perform an advanced search given passed rules. This works in a similar way to the web/UI search pages. You can pass multiple rules as well as joins to create in depth search results

Rules must be sent in groups of 3 using an int (starting from 1) to designate which rules are combined. Use operator ('and'|'or') to choose whether to join or separate each rule when searching.

Refer to the Advanced Search page for details about creating searches.

  • INPUTS
    • ampache_url = (string)
    • ampache_API = (string)
    • operator = (string) 'and'|'or' (whether to match one rule or all)
    • rules = (array) = [[rule_1,rule_1_operator,rule_1_input], [rule_2,rule_2_operator,rule_2_input], [etc]]
    • type = (string) 'song', 'album', 'artist', 'playlist', 'label', 'user', 'video'
    • random = (integer) 0|1 (random order of results; default to 0)
    • offset = (integer)
    • limit' = (integer)

SONG

Example

ARTIST

Example

ALBUM

Example

artists

This takes a collection of inputs and returns artist objects.

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'booleanif true filter is exact rather then fuzzyYES
'add'set_filterISO 8601 Date Format (2020-09-16)YES
Find objects with an 'add' date newer than the specified date
'update'set_filterISO 8601 Date Format (2020-09-16)YES
Find objects with an 'update' time newer than the specified date
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES
'include'string'albums', 'songs' and will include the corresponding XMLYES

Example

artist

This returns a single artist based on the UID of said artist

InputTypeDescriptionOptional
'filter'stringUID of Artist, returns artist XMLNO
'include'arrayArray specified using GET convention, can contain albums or songs and will include the corresponding XML nested in the artist XMLNO

Example

artist_albums

This returns the albums of an artist

InputTypeDescriptionOptional
'filter'integerUID of Artist, returns Album XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

artist_songs

This returns the songs of the specified artist

InputTypeDescriptionOptional
'filter'integerUID of Artist, returns Song XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

albums

This returns albums based on the provided search filters

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'booleanif true filter is exact rather then fuzzyNO
'add'set_filterISO 8601 Date Format (2020-09-16)YES
Find objects with an 'add' date newer than the specified date
'update'set_filterISO 8601 Date Format (2020-09-16)YES
Find objects with an 'update' time newer than the specified date
'offset'integerReturn results starting from this index positionYES
'limit'integerYES
'include'string'albums', 'songs' will include nested in the album XMLYES

Example

album

This returns a single album based on the UID provided

InputTypeDescriptionOptional
'filter'integerUID of Album, returns album XMLNO
'include'arrayArray specified using GET convention, can contain songs and will include the corresponding XML nested in the album XMLNO

Example

album_songs

This returns the songs of a specified album

InputTypeDescriptionOptional
'filter'integerUID of Album, returns song XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

tags

This returns the tags (Genres) based on the specified filter

NOTE For API3 forward compatability, this function is also called with genres

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'booleanif true filter is exact rather then fuzzyYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

tag

This returns a single tag based on UID

NOTE For API3 forward compatability, this function is also called with genre

InputTypeDescriptionOptional
'filter'integerUID of tag, returns tag XMLNO

Example

tag_artists

This returns the artists associated with the tag in question as defined by the UID

NOTE For API3 forward compatability, this function is also called with genre_artists

InputTypeDescriptionOptional
'filter'integerUID of tag, returns artist XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

tag_albums

This returns the albums associated with the tag in question

NOTE For API3 forward compatability, this function is also called with genre_albums

InputTypeDescriptionOptional
'filter'integerUID of tag, returns album XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

tag_songs

returns the songs for this tag

NOTE For API3 forward compatability, this function is also called with genre_songs

InputTypeDescriptionOptional
'filter'integerUID of tag, returns song XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

songs

Returns songs based on the specified filter

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberNO
'add'set_filterISO 8601 Date Format (2020-09-16)YES
Find objects with an 'add' date newer than the specified date
'update'set_filterISO 8601 Date Format (2020-09-16)YES
Find objects with an 'update' time newer than the specified date
'exact'booleanif true filter is exact rather then fuzzyNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

song

returns a single song

InputTypeDescriptionOptional
'filter'integerUID of Song, returns song XMLNO

Example

playlists

This returns playlists based on the specified filter

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberYES
'exact'booleanif true filter is exact rather then fuzzyYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

playlist

This returns a single playlist

InputTypeDescriptionOptional
'filter'stringUID of playlist, returns playlist XMLNO

Example

playlist_songs

This returns the songs for a playlist

InputTypeDescriptionOptional
'filter'stringUID of Playlist, returns song XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

playlist_create

This create a new playlist and return it

InputTypeDescriptionOptional
'name'stringPlaylist nameNO
'type'stringPlaylist type 'public', 'private'YES

Example

playlist_delete

This deletes a playlist

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO

Example

playlist_add_song

This adds a song to a playlist. setting check=1 will not add duplicates to the playlist

InputTypeDescriptionOptional
'filter'integerUID of PlaylistNO
'song'integerUID of song to add to playlistNO

Example

playlist_remove_song

This remove a song from a playlist.

NOTE In API3 this function don't not allow song parameters

InputTypeDescriptionOptional
'filter'stringUID of PlaylistNO
'track'integerTrack number to remove from playlistNO

Example

search_songs

This searches the songs and returns... songs

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for Name returns share XMLNO
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

videos

This returns video objects!

InputTypeDescriptionOptional
'filter'stringValue is Alpha Match for returned results, may be more than one letter/numberNO
'exact'booleanif true filter is exact rather then fuzzyYES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

Example

video

This returns a single video

InputTypeDescriptionOptional
'filter'integerUID of video, returns video XMLNO

Example

stats

Get some items based on some simple search types and filters.

NOTE In API3 this function only returns albums

InputTypeDescriptionOptional
'type'string'newest', 'highest', 'frequent', 'recent', 'forgotten', 'random'NO
'username'stringUsed for recent searches.YES
'offset'integerReturn results starting from this index positionYES
'limit'integerMaximum number of results to returnYES

SONG

Example

ARTIST

Example

ALBUM

Example

user

This get an user public information

InputTypeDescriptionOptional
'username'stringUsername of the user for who to get detailsNO

Example

followers

This get an user followers

InputTypeDescriptionOptional
'username'stringUsername of the user for who to get followers listNO

Example

following

This get the user list followed by an user

InputTypeDescriptionOptional
'username'string(Username of the user for who to get following listNO

Example

toggle_follow

This follow/unfollow an user

InputTypeDescriptionOptional
'username'stringUsername of the user to follow/unfollowNO

Example

last_shouts

This get the latest posted shouts

InputTypeDescriptionOptional
'username'stringUsername of the user for who to get latest shoutsYES
'limit'integerMaximum number of results to returnYES

Example

rate

This rates a library item

InputTypeDescriptionOptional
'type'string'song', 'album', 'artist', 'playlist',NO
'podcast', 'podcast_episode', 'video'
'tvshow', 'tvshow_season'
'id'stringlibrary item idNO
'rating'integerrating between 0-5NO

Example

timeline

This get an user timeline

InputTypeDescriptionOptional
'username'stringUsername of the user for whom to get the timelineNO
'limit'integerMaximum number of results to returnYES
'since'integerUNIXTIME()YES

Example

friends_timeline

This get current user friends timeline

InputTypeDescriptionOptional
'limit'integerMaximum number of results to returnYES
'since'integerUNIXTIME()NO

Example

Control Methods

localplay

This is for controlling localplay

InputTypeDescriptionOptional
'command'string'next', 'prev', 'stop', 'play'NO
  • return
<root>
<localplay>
<command>
<next>|<prev>|<stop>|<play>|<pause>|<add>|<volume_up>|<volume_down>|<volume_mute>|<delete_all>|<skip>|<status>
</command>
</localplay>
</root>

Example

democratic

This is for controlling democratic play

  • ACTION
    • method
      • vote
        • oid (Unique ID of the element you want to vote on)
      • devote
        • oid (Unique ID of the element you want to vote on)
      • playlist (Returns an array of song items with an additional \[VOTE COUNT]\ element)
      • play (Returns the URL for playing democratic play)
InputTypeDescriptionOptional
'oid'integerUID of Song objectNO
'method'stringvote, devote, playlist, playNO
TBC