Console.FM API V2 Beta

Console.FM API V2 Beta is the best way to discover new, trending and popular music amoung the electronica music scene. The API allows you to access our track collection via specific genres and artists. If you would like access please fill out the form.

Overview and Terms of Use

The Console.FM API is available for non-commercial use. Commercial use is possible by prior arrangement. Please contact us if you wish to apply for commercial use of the API.

Any distribution of applications built on top of the Console.fm API must have permission to do so and also present the Console.fm logo in clear site of the user viewing the application. No app built on the Console.fm platform has the permission to be charged for in any form.

Genre Endpoints

GET /GENRES

Returns a list of the currently visible genres.

Params: api_key

$> curl http://console.fm/api/v2/genres?api_key=YOURKEY
---
{
  response: {
    genres: [
      {
        id: 1,
        name: "Breaks"
        slug: "breaks"
      },
      {
        id: 2,
        name: "Chill Out"
        slug: "chill-out"
      }
    ]
  },
  status: {
    code: 0,
    message: "success"
    version: "v2"
  }
}

GET /GENRES/{:id | :slug}

Returns a detailed view of the genre with extra data.

Params: api_key, URL: genre[:id] or genre[:slug]

$> curl http://console.fm/api/v2/genres/1?api_key=YOURKEY
$> curl http://console.fm/api/v2/genres/breaks?api_key=YOURKEY
---
{
  response: {
    genre: {
      id: 1
      name: "Breaks"
      slug: "breaks"
    }
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

GET /GENRES/{:id | :slug}/tracks

Returns a list of all current tracks that are a child of the genre passed.

Params: api_key, URL: genre[:id] or genre[:slug]

$> curl http://console.fm/api/v2/genres/1/tracks?api_key=YOURKEY
$> curl http://console.fm/api/v2/genres/breaks/tracks?api_key=YOURKEY
---
{
  response: {
    tracks: [
      {
        genre_id: 1
        id: 53
        id_str: "metha-dark-smile"
        large_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/400000/90000/6000/200/50/4496250.jpg"
        length: "4:49"
        medium_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/400000/90000/6000/200/40/4496249.jpg"
        name: "Dark Smile"
        playback_count: 925
        published_at: "2011-10-12T00:00:00Z"
        released_at: "2011-10-12T00:00:00Z"
        small_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/400000/90000/6000/200/40/4496248.jpg"
        track_source_url: "http://console.fm/media/s1yhbbs5clzm5ygbowrjsk6zz"
        canonical_url: "http://console.fm/tracks/metha-dark-smile"
        artists: [
          {
            id: 56
            name: "Metha"
            slug: "metha"
          }
        ]
      },  
      {
        genre_id: 1
        id: 36
        id_str: "hedflux-rhythm-prism"
        large_image_url: "http://geo-media.beatport.com/items/imageCatalog/0/800000/90000/2000/100/0/892103.jpg"
        length: "6:30"
        medium_image_url: "http://geo-media.beatport.com/items/imageCatalog/0/800000/90000/2000/100/0/892102.jpg"
        name: "Rhythm Prism"
        playback_count: 1014
        published_at: "2011-01-12T00:00:00Z"
        released_at: "2011-01-12T00:00:00Z"
        small_image_url: "http://geo-media.beatport.com/items/imageCatalog/0/800000/90000/2000/100/0/892101.jpg"
        track_source_url: "http://console.fm/media/ftmaizfj6jwjt84thczozok4f"
        canonical_url: "http://console.fm/tracks/hedflux-neurodriver-energy-vibration"
        artists: [
          {
            id: 21
            name: "Hedflux"
            slug: "hedflux"
          }
        ]
      }
    ]
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

GET /GENRES/{:id | :slug}/artists

Returns a list of all current artists that are a child of the genre passed.

Params: api_key, #URL: genre[:id] or genre[:slug]

$> curl http://console.fm/api/v2/genres/1/artists?api_key=YOURKEY
$> curl http://console.fm/api/v2/genres/breaks/artists?api_key=YOURKEY
---
{
  response: {
    artists: [
      {
        id: 1
        name: "Zeds Dead"
        slug: "zeds-dead"
      },
      {
        id: 2
        name: "Electric Soulside"
        slug: "electric-soulside"
      },
      {
        id: 59
        name: "Johnny Dangerously"
        slug: "johnny-dangerously"
      }
    ]
  }
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

Artist Endpoints

GET /ARTISTS/{:id | :slug}

Returns a detailed description of artist and their genres.

Params: api_key, #URL: artist[:id] or artist[:slug]

$> curl http://console.fm/api/v2/artists/1?api_key=YOURKEY   
$> curl http://console.fm/api/v2/artists/zeds-dead?api_key=YOURKEY
---
{
  response: {
    artist: {
      id: 1
      name: "Zeds Dead"
      slug: "zeds-dead"
      genres: [
        {
          id: 1
          name: "Breaks"
          slug: "breaks"
        }
      ],
      total_tracks: 2
    }
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

GET /ARTISTS/{:id | :slug}/tracks

Returns a full list of the artists tracks.

Params: api_key, #URL: artist[:id] or artist[:slug]

$> curl http://console.fm/api/v2/artists/1/tracks?api_key=YOURKEY   
$> curl http://console.fm/api/v2/artists/zeds-dead/tracks?api_key=YOURKEY
---
{
  response: {
    tracks: [
      {
        genre_id: 1
        id: 11
        id_str: "zeds-dead-rumble-in-the-jungle"
        large_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/0/60000/2000/600/70/4062677.jpg"
        length: "3:52"
        medium_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/0/60000/2000/600/70/4062676.jpg"
        name: "Rumble In The Jungle"
        playback_count: 313
        published_at: "2011-10-04T00:00:00Z"
        released_at: "2011-10-04T00:00:00Z"
        small_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/0/60000/2000/600/70/4062675.jpg"
        track_source_url: "http://console.fm/media/m5wb0r7pitvpqqynpku3mlvof"
        canonical_url: "http://console.fm/tracks/zeds-dead-rumble-in-the-jungle"
        artists: [
          {
            id: 1
            name: "Zeds Dead"
            slug: "zeds-dead"
          }
        ]
      }
    ]
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

Track Endpoints

GET /tracks/{:id | id_str}

Returns a detailed description of a track object.

Params: apikey, :URL track[:id] or track[:idstr]

$> curl http://console.fm/api/v2/tracks/22?api_key=YOURKEY
$> curl http://console.fm/api/v2/tracks/kris-wadsworth-connection?api_key=YOURKEY   
---
{
  response: {
    track: {
      genre_id: 1
      id_str: "kris-wadsworth-connection"
      large_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/100000/0/7000/400/70/4107471.jpg"
      length: "7:01"
      medium_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/100000/0/7000/400/70/4107470.jpg"
      name: "Connection"
      playback_count: 413
      published_at: "2011-10-03T00:00:00Z"
      released_at: "2011-10-03T00:00:00Z"
      small_image_url: "http://geo-media.beatport.com/items/imageCatalog/4000000/100000/0/7000/400/60/4107469.jpg"
      track_source_url: "http://console.fm/media/ajupgmlzlgntjkomekveoxrur"
      canonical_url: "http://console.fm/tracks/kris-wadsworth-connection"
      artists: [
        {
          id: 20
          name: "Kris Wadsworth"
          slug: "kris-wadsworth"
        }
      ]
    }
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

User Endpoints

GET /user/current

Returns a detailed description of a currently authenticated user.

Params: api_key

$> curl http://console.fm/api/v2/user/current?api_key=YOURKEY   
---
{
  response: {
    user: {
      created_at: "2011-10-08T06:33:42Z"
      email: "qlq752@my.utsa.edu"
      identifier: "ywj0upoznktht0k"
    }
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

POST /user/authenticate

Returns a detailed description of a currently authenticated user.

Params: api_key, POST: facebook[:uid], facebook[:token]

$> curl -d "api_key=YOURKEY&uid=100000&token=Akdkjfl3423" http://console.fm/api/v2/user/authenticate
---
{
  response: {
    user: {
      created_at: "2011-10-08T06:33:42Z"
      email: "qlq752@my.utsa.edu"
      identifier: "ywj0upoznktht0k"
    }
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

GET /user/current/facebook

Returns a detailed description of a currently authenticated user’s facebook.

Params: api_key

$> curl http://console.fm/api/v2/user/current/facebook?api_key=YOURKEY   
---
{
  response: {
    facebook: {
      email: "qlq752@my.utsa.edu"
      first_name: "Alex"
      gender: "male"
      last_name: "Manelis"
      link: "http://www.facebook.com/amanelis"
      name: "Alex Manelis"
      nickname: "amanelis"
      uid: "25402005"
    }
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

GET /user/current/favorites

Returns a list of the currently authenticated users favorites are.

Params: api_key

$> curl http://console.fm/api/v2/user/current/favorites?api_key=YOURKEY   
---
{
  response: {
    favorites: [
      {
        id: 1
        track_id: 51
      },
      {
        id: 2
        track_id: 224
      }
    ]
  }
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

GET /user/current/history

Returns a list of the currently authenticated users list of tracks they have listened to.

Params: api_key

$> curl http://console.fm/api/v2/user/current/history?api_key=YOURKEY   
---
{
  response: {
    history: [
      {
        id: 6407
        track_id: 10
      },
      {
        id: 6640
        track_id: 3526
      }
    ]
  },
  status: {
    code: 0
    message: "success"
    version: "v2"
  }
}

Error Responses

Verify Authentic

Your API KEY is most likely incorrent in this case.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "Invalid OAuth access token."
    type: "OAuthException"
    method: "verify_authentic"
  }
}

Check Params

Any number of your parameters could be incorrect.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "Invalid or blank parameters passed."
    type: "BlankParameters"
    method: "check_params"
  }
}

No Record

The resulting API call could not find the object you so desired for.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "No record found."
    type: "EmptySet"
    method: "no_record"
  }
}

Depricated

The method and all its resources have been removed from the API.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "Resource/Method has been removed from this version of the API."
    type: "DepricatedMethod"
    method: "depricated"
  }
}

Version Not Allowed

The developer key you have may be limited in which resources it may be able to access due to permissions.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "Not authorized for this resource."
    type: "PermissionsException"
    method: "version_not_allowed"
  }
}

Not Authorized

The developer key you have may be limited in which resources it may be able to access due to permissions.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "Not authorized for this resource."
    type: "PermissionsException"
    method: "not_authorized"
  }
}

Not Authenticated

A User object has not been authenticated to access this resource.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "User has not been authenticated."
    type: "OAuthException"
    method: "not_authenticated"
  }
}

Invalid Request

A HTTP method that is not allowed was submitted to a resource. The error will automatically detect which HTTP method is allowed and display that in the error message.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  error: {
    version: "v2"
    message: "Invalid HTTP request, expected [GET, POST, PUT, DELETE]."
    type: "HTTPRequestException"
    method: "invalid_request"
  }
}

Successful Response

A correct response will always be rendered as follows.

$> curl http://console.fm/api/v2?api_key=YOURKEY   
---
{
  response: {
    resource: {
      ...
    }
  },
  status: {
    code: 0
    message: "Success"
    version: "v2"
  }
}

Written by: Console FM Dev’s, questions comments email: alex@console.fm