API for Voice Interaction - laughly/external-docs GitHub Wiki

Sign up / Sign in

See the instructions here.

Search for Content

  • GET /api/search/top/artist

    • Takes single param query

        {
     result_name: "Richard Pryor",
     result_type: "artist",
     result_id: "fj39jfjsfj",
     result_data: <artist object>
  }
  • GET /api/search/top/album

    • Takes single param query

        {
     result_name: "Live on the Sunset Strip",
     result_type: "album",
     result_id: "21j29d92jed",
     result_data: <album object>
  }
  • GET /api/search/top/radio

    • Takes single param query

        {
     result_name: "Classic",
     result_type: "radio",
     result_id: "ifn8uhfshjd1",
     result_data: <radio object>
  }
  • GET /api/search/top/any
    • Takes single param query
    • Response will look like any one of the above.

  • If the search yielded no results, result_id will be the empty string.

Play content

On-demand

  • This applies to result_type artist and result_type album.

  • Get artist tracks with
    GET /artist/:artist_id/tracks

  • Get album tracks with
    GET /album/:album_id/tracks

  • The search result field tracks may be undefined, an empty array, or populated.

    • Even if populated, some or all of the tracks might be radio_only; these tracks must be ignored.

  • If search result includes an array of tracks, play them in order (again, skipping any with radio_only: true).

  • To play a track, get the streaming URL at the time of playback with:

    GET /api/stream/:track_id
    {
  id: "1hf8h2rd2",
  name: "Prison",
  stream_url: "https://c21ijdijf2ijf.cloudfront.net/oihawognaoinawofhawoudncnwd",
  artist: { id: "2jiejd2f", name: "Richard Pryor" },
  album: { id: "f1j9ejdjf", name: "Live on the sunset strip" },
  ...
}

  • User can skip these tracks without limit. User can also navigate back to previous tracks. And he/she can seek around within any of these tracks.

  • When you have reached the end of the tracks array, you can switch to radio mode, using the artist's ID as the radio id. Use the artist's name to announce the switch to user. "That concludes the album. Now here's [artist name] radio to keep the laughs coming." (See below on how to play radio.) Once the user is in radio-mode, he/she cannot go back to previous tracks, nor can they seek within a track, and they are limited in how often they can skip a track.

  • If the tracks array is undefined or contains only radio-only tracks, let the user know before launching him or her into the artist's radio.

Radio

  • If the search result has result_type: radio, play the radio by hitting the following endpoint over and over with the radio ID. The responses to these requests will include a stream_url for streaming, plus some metadata about the track.

    GET /api/discovery-playlist/:radio_id/random_track
    {
  id: "ojfwajgawnwif",
  name: "Intro",
  stream_url: "https://c21ijdijf2ijf.cloudfront.net/aouwhgoawhdiawjoghawiudjoawivhwriocn",
  next_skip: "2011-08-30T13:22:53.108Z",
  artist: { id: "faiwhghawdf", name: "Eddie Murphy" },
  album: { id: "iawhhagdnvw", name: "Comedian" },
  ...
}

  • The user is not allowed to go back to previous track or seek within a track.

  • If next_skip is earlier than the current time, user is allowed to skip. If it's later, he/she is not allowed to skip. Make sure to check the value after each skip.

  • The radio may run out of tracks, in which case the server will respond with HTTP status code 451

    • At this point, you could switch the user to Popular, Trending, "My Station", or "Surprise Me" (see below).

  • Special radios:

    • Popular (id=F8gJpDmNol)
    • Trending (id=trending)
    • My Radio (id=me)
    • Surprise Me (id=the_universe)
    • Artist radios: For any artist, you can use his/her ID as a radio ID.