MusicGraph API Documentation

Dynamic Station APIs

API calls for creating an interactive, personalized radio experience that incorporates real-time feedback from the end user. A session ID is created, which maintains listening activity (plays, skips) and user feedback (likes, dislikes) to ensure increasingly personalized radio experience.

The base URL path for user stations is: http://api.musicgraph.com/api/v2/stations/

Create Station Session

Instantiates the station session for dynamic play. A session identifier is returned that can be used with other dynamic methods to get new songs, provide feedback on the station. A session has a limited lifetime and will expire after a certain period of inactivity (typically 24 hours). Nevertheless, all user play & feedback history will be preserved and viewable under the Station Session History api call.

Requires HTTP POST request.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
station_id yes MusicGraph generated ID

ex. c6e5260a-8303-45ea-92eb-caf208e906f2

country yes The country/geo-location of the user

ISO_3166-1 alpha-2 country code e.g. us, br, es

dmca no DMCA compliance flag, default is set to "true" ex. dmca=false if you want to override a dmca compliant station.

Example POST

curl -X POST -H "Content-Type: application/json" -d '{"country":"us"}' http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2?api_key=c8303e90962e3a5ebd5a1f260a69b138

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        "station_session_id": "43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc",
        "new_session": true
      }
    }
    

Get Station Next Track (Dynamic)

Songs in the playlist are fetched, one at a time, using the dynamic/next method. The playlist is dynamic in that it is adapted dynamically based on the listener's feedback e.g. Play, Skip, Like, Dislike.

Parameter Required Description Example
api_key yes The developer API key

api_key=[your-api-key]

station_id yes MusicGraph generated ID

ex. c6e5260a-8303-45ea-92eb-caf208e906f2

session_id yes Generated SessionID ex. 43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc
action yes Triggers that advance the station queue Values are: first|next|error|skip
duration no The duration of the previously played track Values are in seconds ex. 235
country no Users country, will override what has been set at the session level ISO_3166-1 alpha-2 country code e.g. us, br, es

Action values are stored in the users taste profile and session histories are are used to dynamically steer the station
- action=first is required to initialize and load the first track
- action=next will return the next song(s) in the station, should be passed if the track has been played in full
- action=skip, returns the next song in the station, should be passed if the track has been skipped
- action=error, returns the next song in the station, should be passed if the track has NOT been played or error has occurred during streaming

Example GET - First Track

curl -X GET -H "Content-Type: application/json" "http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2/43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc?api_key=c8303e90962e3a5ebd5a1f260a69b138&action=first"

Example GET - Next Track

curl -X GET -H "Content-Type: application/json" "http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2/43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc?api_key=c8303e90962e3a5ebd5a1f260a69b138&action=next"

Example Response

    {
      status: {
        code: 0,
        message: "Success",
        api: "v2"
      },
      data: {
        popularity: 0.49,
        track_artist_id: "eb615908-a6b5-11e0-b446-00251188dd67",
        release_year: 1992,
        title: "Chloe Dancer/Crown of Thorns",
        track_album_id: "a74db4d1-11a4-604d-18c1-5a1221796154",
        entity_type: "track",
        track_ref_id: "28551427",
        artist_name: "Mother Love Bone",
        main_genre: "rock",
        label_name: "Universal/Island Def Jam",
        track_album_ref_id: "28551393",
        album_title: "Mother Love Bone",
        performer_name: "Mother Love Bone",
        track_index: "17",
        duration: 501,
        isrc: "USWWW0134840",
        id: "03fe5b79-8c38-a42c-db1d-7185c7f0a353",
        track_artist_ref_id: "23657"
      }
    }
    

Post Feedback

Provides the ability to post user feedback on artists/songs played during the session. Feedback is applied to the item specified by the given artist_id or track_id and multiple posts can be made during the active session.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
station_id yes MusicGraph generated ID

ex. c6e5260a-8303-45ea-92eb-caf208e906f2

session_id yes Generated SessionID ex. 43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc
id no object id e.g. artist_id, track_id ex. 1f4ae53d-7216-3f08-be76-52cc82e679cc
like_song no liked track, track_id would need to be passed. e.g. thumbs up  
unlike_song no disliked track, track_id would need to be passed. will not appear again during the session. e.g. thumbs down  
like_artist no liked artist associated with the given track, artist_id would need to be passed. e.g. favoriting artist  
unlike_artist no disliked artist, artist_id would need to be passed. will not appear again during the session. e.g. ban artist  

Example POST

curl -X POST -H "Content-Type: application/json" -d '{"id":"1f4ae53d-7216-3f08-be76-52cc82e679cc","feedback":"like_song"}' http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2/43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc/feedback?api_key=c8303e90962e3a5ebd5a1f260a69b138

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        
      }
    }
  

Station Session History

Retrieves information about a dynamic station session.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
station_id yes MusicGraph generated ID

ex. c6e5260a-8303-45ea-92eb-caf208e906f2

session_id yes Generated SessionID ex. 43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc

Example GET

curl -X GET -H "Content-Type: application/json" http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2/43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc/history?api_key=c8303e90962e3a5ebd5a1f260a69b138

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        "plays": [
          {
            "track_title": "Chloe Dancer/Crown of Thorns",
            "play_duration": 501,
            "artist_name": "Mother Love Bone",
            "tstamp": 1420665185776,
            "action": "next",
            "duration": 501,
            "track_id": "03fe5b79-8c38-a42c-db1d-7185c7f0a353"
          },
          {
            "track_title": "Say Hello 2 Heaven",
            "play_duration": 382,
            "artist_name": "Temple of the Dog",
            "tstamp": 1420665849847,
            "action": "next",
            "duration": 382,
            "track_id": "1f4ae53d-7216-3f08-be76-52cc82e679cc"
          },
          {
            "track_title": "Even Flow",
            "play_duration": 0,
            "artist_name": "Pearl Jam",
            "tstamp": 1420665905848,
            "action": "skip",
            "duration": 303,
            "track_id": "ee6c6759-86a0-2dc1-f529-718a9029357c"
          }
        ],
        "feedback": {
          "like_song": [
            {
              "track_title": "Say Hello 2 Heaven",
              "id": "1f4ae53d-7216-3f08-be76-52cc82e679cc"
            }
          ]
        }
      }
    }
  

Delete Station Session

Provides the ability to delete the current station session. Requires HTTP DELETE request.

Parameter Required Description Example
api_key yes The developer API key

api_key=[your-api-key]

station_id yes MusicGraph generated ID

ex. c6e5260a-8303-45ea-92eb-caf208e906f2

session_id yes Generated SessionID ex. 43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc

Example DELETE

curl -X DELETE -H "Content-Type: application/json" http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2/43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc?api_key=c8303e90962e3a5ebd5a1f260a69b138

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        
      }
    }
    

Premium Playlisting Call (Alternative to Dynamic Next)

Allows for a personalized and interactive playlisting experience, providing up to 100 tracks. Passing in a previously created station session id generates a playlist that incorporates an end user's personal preferences and real-time feedback. In addition, the playlist inherits all settings information when the session was created e.g. dmca, country, and etc. Information is retained and stored against the users profile and session history. Additional feedback operations are available such as "play" & "skip" to record actions. See table and diagram below.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
session_id yes Generated SessionID ex. 43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc
limit no By default we return 20 records, max 100 ex. &limit=10
offset no Allows for paginating through the results ex. &offset=5

Example GET

curl -X GET -H "Content-Type: application/json" "http://api.musicgraph.com/api/v2/playlist?station_session_id=33dd8e00-7551-4d5e-a0a3-6cd1fb79bae8&limit=20&offset=5&api_key=c8303e90962e3a5ebd5a1f260a69b138"

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "pagination": {
        "count": 20,
        "offset": 5
      },
      "data": [
        {
          "popularity": 0.71,
          "track_artist_id": "e2ffceb5-a6b5-11e0-b446-00251188dd67",
          "release_year": 2009,
          "title": "Just Breathe",
          "track_album_id": "2fb4ad0e-d6d7-e79a-2da1-217a2467ec04",
          "entity_type": "track",
          "track_ref_id": "71027843",
          "artist_name": "Pearl Jam",
          "main_genre": "alternative/indie",
          "label_name": "Island Records",
          "track_album_ref_id": "71027825",
          "album_title": "Backspacer",
          "performer_name": "Pearl Jam",
          "track_index": "5",
          "duration": 216,
          "isrc": "USA320900005",
          "id": "d3904f90-4738-b1c9-45c6-e11786020b63",
          "track_artist_ref_id": "43089"
        },
        {
          "popularity": 0.69,
          "track_artist_id": "e79ad33c-a6b5-11e0-b446-00251188dd67",
          "release_year": 2007,
          "title": "Society",
          "track_album_id": "0e4915dd-6a81-33db-b642-f8c431d08824",
          "entity_type": "track",
          "track_ref_id": "11574013",
          "artist_name": "Eddie Vedder",
          "main_genre": "soundtracks",
          "label_name": "J RECORDS",
          "track_album_ref_id": "11573997",
          "album_title": "Into the Wild [Original Soundtrack]",
          "performer_name": "Eddie Vedder",
          "track_index": "8",
          "duration": 236,
          "isrc": "USJY50700008",
          "id": "b8227055-bd98-1ff3-cc83-0194f61a2f49",
          "track_artist_ref_id": "9452"
        },
        ....
      ]
    }
    

Additional Feedback post options when using the Premium Playlisting option during the active session.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
station_id yes MusicGraph generated ID

ex. c6e5260a-8303-45ea-92eb-caf208e906f2

session_id yes Generated SessionID ex. 43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc
id no object id e.g. artist_id, track_id ex. 1f4ae53d-7216-3f08-be76-52cc82e679cc
play_song no tracks a song play (full); used to capture play events when using the premium playlisting endpoint only.  
skip_song no tracks a song skip; used to capture play events when using the premium playlisting endpoint only.  

Example POST

curl -X POST -H "Content-Type: application/json" -d 
             '{"id":"1f4ae53d-7216-3f08-be76-52cc82e679cc",
               "feedback":"play_song" or "skip_song",
               “duration”: “125”,  <= optional, stream duration; serves for recommendation analysis.
               “country”: “us” <= optional, users current geo during listening
             }' 
            http://api.musicgraph.com/api/v2/station/c6e5260a-8303-45ea-92eb-caf208e906f2/43706be9-aa9b-4b7f-91f1-2b47d3c6c4bc/feedback?api_key=c8303e90962e3a5ebd5a1f260a69b138

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        
      }
    }
  

Flow Diagram

User Playlist vs Stations