MusicGraph API Documentation

User Stations API

API calls for creating and managing user stations in your graph.

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

Create Station

Creates a user station based on various seed types e.g. artists, tracks, genres, and decades. Requires HTTP POST request.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456
artist_ids no 1:5 (max) artist id's comma separated ex. e3109b71-a6b5-11e0-b446-00251188dd67
track_ids no 1:5 (max) track id's comma separated ex. f05e067b-a6c0-11e0-b446-00251188dd67
genres no 1 (max) genre value ex. rock (see Dictionary for list)
decades no 1 (max) decade value ex. 1990s (see Dictionary for list)

Notes:

1) Combinations (e.g. mixed seed types) are only applicable to genres and decades - max 1 each ex: { "decades": "1980s" , "genres": "rock"}

Example POST for an artist station (Red Hot Chili Peppers)

curl -X POST -H "Content-Type: application/json" -d '{"artist_ids":"e3109b71-a6b5-11e0-b446-00251188dd67"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example POST for a multi-seeded track station (Adel's "Rolling in the Deep" and Duffy's "Mercy")

curl -X POST -H "Content-Type: application/json" -d '{"track_ids":"f05e067b-a6c0-11e0-b446-00251188dd67,4c77fa32-50b5-9f28-6c36-0db589ff6242"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example POST for genre seeded station

curl -X POST -H "Content-Type: application/json" -d '{"genres":"blues"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example POST for a decade seeded station

curl -X POST -H "Content-Type: application/json" -d '{"decades":"1970s"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example POST for a combined type seeded station **Only genres and decades can be combined

curl -X POST -H "Content-Type: application/json" -d '{"genres":"rock", "decades":"1980s"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

    {
      "status": {
         "code": 0,
         "message": "Success",
         "api": "v2"
      },
      "data": {
         "station_session_id": "[generated sessionid]",
         "station_id": "[generated station id]"
      }
    }
    

Get Station Meta

Retrieves the meta information about a particular station.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456
station_id yes MusicGraph generated ID ex. 83afbafd-26be-46b8-bc04-cc2ffde12b88

Example GET

curl -X GET -H "Content-Type: application/json" http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations/e4fe3bf6-fd50-496c-9749-0750ed44e149?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        "name": "Red Hot Chili Peppers",
        "settings": {
          "popularity": "any",
          "year": "retro,2014",
          "tempo": "any",
          "similarity": "any"
        },
        "meta": {
          "includes": [
            {
              "name": "Red Hot Chili Peppers",
              "entity_type": "artist",
              "artist_ref_id": "27692",
              "gender": "Male",
              "main_genre": "Pop/Rock",
              "decade": "1980s / 1990s / 2000s / 2010s"
            }
          ]
        },
        "date_created": "1420597562819",
        "artist_id": "e3109b71-a6b5-11e0-b446-00251188dd67",
        "additional_seeds": [
          
        ],
        "id": "e4fe3bf6-fd50-496c-9749-0750ed44e149"
      }
    }
    

Update Station Meta

Provides the ability to modify station meta information. Requires HTTP PUT request.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456

Updatable fields are:

name

Example PUT

curl -X PUT -H "Content-Type: application/json" -d '{"name":"My Favorite Red Hot Chili Peppers station"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations/e4fe3bf6-fd50-496c-9749-0750ed44e149?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        "station_id": "e4fe3bf6-fd50-496c-9749-0750ed44e149"
      }
    }
    

Get Station Settings

Retrieves the tuning setting of a particular station. When a new station is created, the tuning settings are set to default values (see Update Station Settings for details).

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456
station_id yes MusicGraph generated ID ex. e4fe3bf6-fd50-496c-9749-0750ed44e149

Example GET

curl -X GET -H "Content-Type: application/json" http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations/e4fe3bf6-fd50-496c-9749-0750ed44e149/settings?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

    {
      "status": {
        "code": 0,
        "message": "Success",
        "api": "v2"
      },
      "data": {
        "popularity": "any",
        "year": "retro,2014",
        "tempo": "any",
        "similarity": "any"
      }
    }
    

Update Station Settings

Provides the ability to tune a station by modfying specific settings such as popularity, similarity, tempo, and release year. Requires HTTP PUT request.

Station Setting description and values:
- Popularity: Track Popularity. By default, set to "any". Values range between 1-10 (Low to High)
- Similarity: Artist Similarity. By default, set to "any". Values range between 1-10 (Low to High)
- Tempo: Track Tempo. By default, set to "any". Values are slow, moderate, fast
- Year: Release Year. By default, set to retro,2014. Must pass a to,from year values.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456
station_id yes MusicGraph generated ID ex. e4fe3bf6-fd50-496c-9749-0750ed44e149

Updatable fields are:

popularity, similarity, tempo, year

Example PUT

curl -X PUT -H "Content-Type: application/json" -d ' {"tempo":"moderate","similarity":"5","popularity":"5","year":"1980,2014"}' http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations/e4fe3bf6-fd50-496c-9749-0750ed44e149/settings?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

    {
      status: {
        code: 0,
        message: "Success",
        api: "v2"
      },
      data: {
        popularity: "5",
        year: "1980,2014",
        tempo: "moderate",
        similarity: "5"
      }
    }
    

Get a list of user stations

Retrieves the list of stations created by the user.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456
limit no By default, the API will return 20 results. Use the limit query string parameter to return a custom number of results (max 100). &limit=5
offset no Use the offset query parameter to perform pagination on the results set. &offset=2

Example GET

      curl -X GET -H "Content-Type: application/json" http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

      {
        "status": {
          "code": 0,
          "message": "Success",
          "api": "v2"
        },
        "pagination": {
          "count": 2,
          "total": 2,
          "offset": 1
        },
        "data": [
          {
            "name": "Red Hot Chili Peppers",
            "settings": {
              "popularity": "any",
              "year": "retro,2014",
              "tempo": "any",
              "similarity": "any"
            },
            "meta": {
              "includes": [
                {
                  "name": "Red Hot Chili Peppers",
                  "entity_type": "artist",
                  "artist_ref_id": "27692",
                  "gender": "Male",
                  "main_genre": "Pop/Rock",
                  "decade": "1980s / 1990s / 2000s / 2010s"
                }
              ]
            },
            "date_created": "1420597562819",
            "artist_id": "e3109b71-a6b5-11e0-b446-00251188dd67",
            "additional_seeds": [],
            "id": "e4fe3bf6-fd50-496c-9749-0750ed44e149"
          },
			...
        ]
      }
    

Delete Station

Provides the ability to delete a specific station. Requires HTTP DELETE request.

Parameter Required Description Example
api_key yes The developer API key api_key=[your-api-key]
user_id yes Namespaced userid e.g. [account_id]:[user_id] ex. 2445580905922:123456
station_id yes MusicGraph generated ID ex. e4fe3bf6-fd50-496c-9749-0750ed44e149

Example DELETE

curl -X DELETE -H "Content-Type: application/json" http://api.musicgraph.com/api/v2/user/2445580905922:123456/stations/e4fe3bf6-fd50-496c-9749-0750ed44e149?api_key=c8303e90962e3a5ebd5a1f260a69b138
    

Example Response

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