API Documentation

This page will explain how to use Pidora's API. This is the same API used internally for most of Pidora's functions.

The Connection

The API is available at /api and accepts a GET/POST json request. The data sent must be valid JSON and a response will also be in JSON. There are two main fields: "method" and "id". These two fields must be filled with a string and an integer, respectively. Some methods may require more fields; but these are the only ones required with each request.

The Methods

GetSongInfo

Returns the currently playing song information as well as any message that needs to be delivered to the client.

Example request {"method":"GetSongInfo", "id":1}

Example response:

{
  "msg":null,
  "song":{
    "album":"Volume IV: Louis Armstrong And Earl Hines",
    "loved":false,
    "title":"No (Papa,No)",
    "explainURL":"http://www.pandora.com/louis-armstrong/volume-4-louis-armstrong-earl-hines/no-papano",
    "artist":"Louis Armstrong",
    "isSong":true,
    "songPlayed":0,
    "artURL":"http://cont-sv5-2.pandora.com/images/public/amz/3/2/2/4/074644514223_500W_500H.jpg",
    "songDuration":0
    
  },
  "method":"GetSongInfo",
  "id":1
}

Most of these are self explanatory. Below I'll explain the less obvious ones.

• msg is any message to be delivered to the user. Examples include "Skipped", "Loved", "Shutdown", etc.
• explainURL is the pandora.com url where the song's information is listed. This is used internally to get the song's explanation (see next method)
• isSong is a boolean variable that tells whether or not the currently playing file is a song or not. This is used by the UI to determine whether to hide the controls or not. For example, when NPR is playing, isSong is false so we hide the controls.
• artURL is the location of the albumart. This string may be empty at times.
• songPlayed and songDuration are not yet implemented and will always be 0.

GetExplanation

Returns a string explaining why the track is being played. This should only be used when isSong is true.

Example request: {"method":"GetExplanation", "id":1}

Example response:

{
  "explanation":"We're playing this track because it features new orleans jazz elements, a mid-tempo dance style, trumpet head,  a clarinet solo, a great trumpet solo, light drumming, a contrapuntal melodic presentation, a lazy swing groove, a blues song form, and many other similarities as identified by the Music Genome Project.",
  "id":1,
  "method":"GetExplanation"
}

GetStationData

Returns an array of strings with the index of the string corresponding to the station's number and the string being the station's name.

Requires an additional field: index which is an integer.

Example request: {"method":"GetStationData", "id":1, "index":1}

Example response:

{
  "stationData":{
    "index":1,
    "stations":[
      "Stereo Love Radio",
      "Still Alive Radio",
      "Swing Jazz",
      "Today's Hits Radio"
    ],
    "back":0,
    "next":null
    
  },
  "method":"GetStationList",
  "id":1
}

• index is an echo of the index you provided.
• stations is an array of the stations with the array index used to select the stations along with the index (see next method).
• back/next gives the previous/next page's index if available. May be an integer or NULL.

ChangeStation

Changes the currently playing station to the one specified.

Requires an additional field: stationID which is an integer. To form the stationID take the index of the GetStationData request and concatenate it with the index of the string in the array. For example, the GetStationData request that holds "Swing Jazz" has an index of 1. The location in the array of "Swing Jazz" is 2. Therefore, to play "Swing Jazz", stationID should be 12 (NB: For arrays where the index is 0, do not include the "0". Correct JSON integers must begin with a 0, 1-9, or be null. Sending 09 is incorrect. However, if you do send it Pidora will correct for that.).

Example request: {"method":"ChangeStation", "id":1, "stationID":12}

Example response:

{
  "id":1,
  "stationID":12,
  "method":"ChangeStation",
  "response":"ok"
}

Control

The method used to control pianobar, including pausing, skipping, loving, etc.

Requires an additional field: command. command has a limited number of appropriate values. They are pause, next, love, ban, tired, volumeup, volumedown.

Example request: {"method":"Control", "id":1, "command":"next"}

Example response:

{
  "id":1,
  "command":"next",
  "method":"Control",
  "response":"ok"
}

Pianobar.Start / Pianobar.Quit

Starts and stops pianobar.

Example request: {"method":"Pianobar.Quit", "id":1}

Example response if pianobar was running:

{
  "id":1,
  "method":"Pianobar.Quit",
  "response":"ok"
}

Example response if pianobar was not running:

{
  "id":1,
  "method":"Pianobar.Quit",
  "response":"bad"
}