XML API

Ashot Nazaryan edited this page Aug 26, 2016 · 22 revisions

Ampache's XML API

Compatible Versions: >= 350001

Ampache Provides an API for pulling out it's meta data in the form of simple XML documents. This was originally created for use by Amarok, but there is no reason it couldn't be used to create other front-ends to the Ampache data. Access to the API is controlled by the Internal Access Control Lists. The KEY defined in the ACL is the passphrase that must be used to establish an API session. Currently all requests are limited to a maximum of 5000 results for performance reasons. To get additional results pass offset as an additional parameter. If you have any questions or requests for this API please submit a Feature Request. All dates in the API calls should be passed as ISO 8601 dates.

Sending Handshake Request

Multiple authentication methods are available, described in the next sections.

User / Password

The handshake is a combination of the following three things

  • Encoded Passphrase
  • Timestamp
  • Username

The key that must be passed to Ampache is SHA256(TIME+KEY) where KEY is SHA256('PASSWORD'). Below is a PHP example

  $time = time(); 
  $key = hash('sha256','mypassword');
  $passphrase = hash('sha256',$time . $key); 

Once you've generated the encoded passphrase, you can call the following URL (localhost/ampache is the location of your Ampache installation)

http://localhost/ampache/server/xml.server.php?action=handshake&auth=PASSPHRASE&timestamp=TIME&version=350001&user=USER

Api Key

The key that must be passed to Ampache is the API Key generated for a specific user (none by default, only the administrator can generate one). Then call the following URL (localhost/ampache is the location of your Ampache installation):

http://localhost/ampache/server/xml.server.php?action=handshake&auth=API_KEY&version=350001

Other handshake-related stuff

Ampache sheme

To standardize how to transfer Ampache connection information, the following Ampache scheme is defined.

ampache://authentication@hostname[:port]/subdirectory[#parameters]

for example:

  • ampache://myuser:mypwd@localhost/ampache
  • ampache://yourapikey@localhost:993/ampache#ssl=true

Application Name

By default Ampache uses USER_AGENT as application name but this could also be defined through http query string. Add &client=YourAppName to override the application name. This parameter also works on stream sessions.

Geolocation

  • Latitude
  • Longitude
  • Place name

Optionally, you can also provide geolocation information &geo_latitude=$latitude&geo_longitude=$longitude, with an optional place name if you already know coordinates match &geo_name=$placename.

Result

If your authenticated User and IP match a row in the Access List the following will be returned.

  <root>
      <auth>AUTHENTICATION TOKEN</auth>
      <version>APIVERSION</version>
      <update>Last Update ISO 8601 Date</update>
      <add>Last Add ISO 8601 Date</add>
      <clean>Last Clean ISO 8601 Date</clean>
      <songs>Total # of Songs</songs>
      <artists>Total # of Artists</artists>
      <albums>Total # of Albums</albums>
      <tags>Total # of Tags</tags>
      <videos>Total # of Videos</videos>
  </root>

All future interactions with the Ampache API must include the AUTHENTICATION_TOKEN as a GET variable named auth.

Errors

All errors will be returned as an XML document as specified in the XML API Error Document. When possible the text part of the message will be translated into the users configured language.

Methods

All methods must be passed as action=METHODNAME. All methods except the handshake can take an optional offset=XXX and limit=XXX. The limit determines the maximum number of results returned. The offset will tell Ampache where to start in the result set. For example if there are 100 total results and you set the offset to 50, and the limit to 50 Ampache will return results between 50 and 100. The default limit is 5000. The default offset is 0.

You can also pass it limit=none to overcome the limit limitation and return all the matching elements.

Non-Data Methods

  • handshake
    • timestamp (Timestamp used in seed of password hash. Required if login/password authentication)
    • auth (Timestamp . Password SHA hash) OR (API Key)
    • version (API Version that the application understands)
    • username (Required if login/password authentication)
  • ping
    • auth (Session ID is optional) returns version information and extends the session if passed
  • url_to_song
    • url (Full Ampache URL from server, translates back into a song XML)

Data Methods

  • artists
    • filter (Value is Alpha Match for returned results, may be more then one letter/number)
    • exact (Boolean, if true filter is exact rather then fuzzy)
    • add (ISO 8601 Date Format assumed filter method is newer then specified date, however [START]/[END] can be specified to receive only results added between two dates)
    • update (ISO 8601 Date Format assumed filter method is newer then specified date, however [START]/[END] can be specified to receive only results updated between two dates)
    • include
  • artist
    • filter (UID of Artist, returns artist XML)
    • include
  • artist_songs
    • filter (UID of Artist, returns song XML)
  • artist_albums
    • filter (UID of Artist, returns Album XML)
  • albums
    • filter (Value is Alpha Match for returned results, may be more then one letter/number)
    • exact (Boolean, if true filter is exact rather then fuzzy)
    • add (ISO 8601 Date Format assumed filter method is newer then specified date, however [START]/[END] can be specified to receive only results added between two dates)
    • update (ISO 8601 Date Format assumed filter method is newer then specified date, however [START]/[END] can be specified to receive only results updated between two dates)
    • include
  • album
    • filter (UID of Album, returns album XML)
    • include
  • album_songs
    • filter (UID of Album, returns song XML)
  • tags
    • filter (Value is Alpha Match for returned results, may be more then one letter/number)
    • exact (Boolean, if true filter is exact rather then fuzzy)
  • tag
    • filter (UID of tag, returns tag XML)
  • tag_artists
    • filter (UID of tag, returns artist XML)
  • tag_albums
    • filter (UID of tag, returns album XML)
  • tag_songs
    • filter (UID of tag, returns song XML)
  • songs
    • filter (Value is Alpha Match for returned results, may be more then one letter/number)
    • add (ISO 8601 Date Format assumed filter method is newer then specified date, however [START]/[END] can be specified to receive only results added between two dates)
    • update (ISO 8601 Date Format assumed filter method is newer then specified date, however [START]/[END] can be specified to receive only results updated between two dates)
    • exact (Boolean, if true filter is exact rather then fuzzy)
  • song
    • filter (UID of Song, returns song XML)
  • playlists
    • filter (Value is Alpha Match for returned results, may be more then one letter/number)
    • exact (Boolean, if true filter is exact rather then fuzzy)
  • playlist
    • filter (UID of playlist, returns playlist XML)
  • playlist_songs
    • filter (UID of Playlist, returns song XML)
  • playlist_create
    • name (Playlist name)
    • type (Playlist type [public|private]. Optional)
  • playlist_delete
    • filter (UID of playlist)
  • playlist_add_song
    • filter (UID of playlist)
    • song (UID of song to add to playlist)
  • playlist_remove_song
    • filter (UID of playlist)
    • track (Track number to remove from playlist)
  • search_songs
    • filter (Value is Alpha Match for Song Title, Artist Name, Album Name, Genre Name returns song XML)
  • videos
    • filter (Value is Alpha Match for returned results, may be more then one letter/number)
    • exact (Boolean, if true filter is exact rather then fuzzy)
  • video
    • filter (UID of video, returns video XML)
  • stats
    • type (Type of album stats to retrieve [newest|highest|frequent|recent|flagged|random])
    • username (Username filter, only if type is recent for now. Optional)
  • user
    • username (Username of the user for who to get details)
  • followers
    • username (Username of the user for who to get followers list)
  • following
    • username (Username of the user for who to get following list)
  • toggle_follow
    • username (Username of the user to follow/unfollow)
  • last_shouts
    • username (Username of the user for who to get latest shouts. Optional)
  • rate
    • type (library item type, album|artist|song|video)
    • id (library item id)
    • rating (rating between 0-5)
  • timeline
    • username (Username of the user for who to get the timeline)
  • friends_timeline

Control Methods

  • localplay
    • command
      • next (Advance to Next Localplay Item)
      • prev (Return to Previous Localplay Item)
      • stop (Stop Localplay Instance)
      • play (Play Localplay Instance)
  • democratic
    • method
      • vote
        • oid (Unique ID of the element you want to vote on)
        • type (Type of object, only song is currently accepted so this is optional)
      • devote
        • oid (Unique ID of the element you want to vote on)
        • type (Type of object, only song is currently accepted so this is optional)
      • playlist (Returns an array of song items with an additional [VOTE COUNT] element)
      • play (Returns the URL for playing democratic play)

Request URL Examples

For the purpose of this example the Ampache host is 'localhost' and the path to Ampache is /ampache

Requesting all genres who's name starts with Rock

http://localhost/ampache/server/xml.server.php?action=tags&auth=1234567890123456789012345678901&filter=Rock

Requesting all song titles, with an offset of 5000

localhost/ampache/server/xml.server.php?action=songs&auth=12345678901234567890123456789012&offset=5000

XML Document Examples

All XML Documents that have a element may have 0 or more tag elements associated with them. Each tag element has an attribute ''count'' that indicates the number of people who have specified this tag.

Artists XML Document. ID's are Ampache's unique Identifier for the artist.

  <root>
  <artist id="12039">
          <name>Metallica</name>
          <albums># of Albums</albums>
          <songs># of Songs</songs>
          <tag id="2481" count="2">Rock & Roll</tag>
          <tag id="2482" count="1">Rock</tag>
          <tag id="2483" count="1">Roll</tag>
          <preciserating>3</preciserating>
          <rating>2.9</rating>
  </artist>
  <artist id="129348">
          <name>AC/DC</name>
          <albums># of Albums</albums>
          <songs># of Songs</songs>
          <tag id="2481" count="2">Rock & Roll</tag>
          <tag id="2482" count="2">Rock</tag>
          <tag id="2483" count="1">Roll</tag>
          <preciserating>3</preciserating>
          <rating>2.9</rating>
  </artist>
  </root>

Album XML Document. ID's are Ampache's unique identifier for the album and artist associated.

  <root>
  <album id="2910">
          <name>Back in Black</name>
          <artist id="129348">AC/DC</artist>
          <year>1984</year>
          <tracks>12</tracks>
          <disk>1</disk>
          <tag id="2481" count="2">Rock & Roll</tag>
          <tag id="2482" count="1">Rock</tag>
          <tag id="2483" count="1">Roll</tag>
          <art>http://localhost/image.php?id=129348</art>
          <preciserating>3</preciserating>
          <rating>2.9</rating>
  </album>
  </root>

Single Song XML document, includes references to its parent objects.

  <root>
  <song id="3180">
          <title>Hells Bells</title>
          <artist id="129348">AC/DC</artist>
          <album id="2910">Back in Black</album>
          <tag id="2481" count="3">Rock & Roll</tag>
          <tag id="2482" count="1">Rock</tag>
          <tag id="2483" count="1">Roll</tag>
          <track>4</track>
          <time>234</time>
          <url>http://localhost/play/index.php?oid=123908...</url>
          <size>Song Filesize in Bytes</size>
          <art>http://localhost/image.php?id=129348</art>
          <preciserating>3</preciserating>
          <rating>2.9</rating>
  </song>
  </root>

Tag XML Document, includes counts for it's child objects

  <root>
  <tag id="2481">
          <name>Rock & Roll</name>
          <albums>84</albums>
          <artists>29</artists>
          <songs>239</songs>
          <video>13</video>
          <playlist>2</playlist>
          <stream>6</stream>
  </tag>
  </root>

Playlist XML Document, includes counts for it's child objects

  <root>
  <playlist id="1234">
          <name>The Good Stuff</name>
          <owner>Karl Vollmer</owner>
          <items>50</items>
          <tag id="2481" count="2">Rock & Roll</tag>
          <tag id="2482" count="2">Rock</tag>
          <tag id="2483" count="1">Roll</tag>
          <type>Public</type>
  </playlist>
  </root>

Video XML Document -- Attention UIDs for video elements are non-unique against song.id

  <root>
  <video id="1234">
           <title>Futurama Bender's Big Score</title>
           <mime>video/avi</mime>
           <resolution>720x288</resolution>
           <size>Video Filesize in Bytes</size>
           <tag id="12131" count="3">Futurama</tag>
           <tag id="32411" count="1">Movie</tag>
           <url>http://localhost/play/index.php?oid=123908...</url>
  </video>
  </root>