alfiyazi/mixcloud

Ruby wrapper of the Mixcloud API. Visit http://www.mixcloud.com/developers/documentation/ for more info

Mixcloud¶ ↑

The Mixcloud gem is a ruby wrapper of the Mixcloud.com API. It enables you to create Ruby objects of Mixcloud resources such as Cloudcast, Artist, etc. by providing their API urls.

Furthermore, it provides a Search functionality which returns Mixcloud resources as an array of Ruby objects instead of JSON data. For more info check

• www.mixcloud.com/developers/documentation/

This gem has not yet been tested with a Rails app. So it is still pretty much a beta. But feel free to test it, use it, drop me a note if you think something needs to be changed or added, or if something isn’t quite working.

Installation¶ ↑

sudo gem install mixcloud

And then require Mixcloud

require 'mixcloud'

# Examples

makoto = Mixcloud::User.new('http://api.mixcloud.com/makoto')
makoto.cloudcasts_url         # => 'http://api.mixcloud.com/makoto/cloudcasts/'

cinematic_mix = Mixcloud::Cloudcast.new('http://api.mixcloud.com/rico-casazza/cinematic-mix-vol-ii/')
cinematic_mix.tags            # => ["http://api.mixcloud.com/tag/cinematic/?metadata=1",
                                    "http://api.mixcloud.com/tag/dub-chill-out-downtempo/?metadata=1", 
                                    "http://api.mixcloud.com/tag/soundscape/?metadata=1",
                                    "http://api.mixcloud.com/tag/soundtrack/?metadata=1", 
                                    "http://api.mixcloud.com/tag/trip-hop/?metadata=1"]

Usage¶ ↑

Search functionality¶ ↑

The Mixcloud gem provide a search functionality for the following Mixcloud resources: Artist, Cloudcast, User and Tag.

Say if you are looking for an artist named ‘Dorian Concept’:

Mixcloud::Search.find_artist('dorian concept')

It will return an array of Artist objects, all with the words ‘dorian concept’ in their names. Behind the scenes, Mixcloud::Search builds a query string for you, so you don’t have to worry about whitespaces. Same goes for:

Mixcloud::Search.find_cloudcast('some text')
Mixcloud::Search.find_user('some text')
Mixcloud::Search.find_tag('some text')

Create Mixcloud Resources¶ ↑

You can create Ruby objects of the following Mixcloud resources: Artist, Category, Cloudcast, Tag, Track and User. In order to do that, you must provide its API url to the constructor.

What do you mean by API url?¶ ↑

Let’s say you want to make a ruby object of the user Mary Anne Hobbs, and her public profile is on

http://www.mixcloud.com/MaryAnneHobbs/

By API url, I mean replacing the ‘www’ in her URL with ‘api’, so you get

http://api.mixcloud.com/MaryAnneHobbs/

Then in your code:

mary_anne_hobbs = Mixcloud::User.new('http://api.mixcloud.com/MaryAnneHobbs/')

Another note regarding the API url, when you enter the API url in the browser, you will see a bunch of data in JSON. But when you append the API url with ‘?metadata=1’, thus

'http://api.mixcloud.com/MaryAnneHobbs/?metadata=1'

, then you will see.… well, more useful data.

What you need to know is that the Mixcloud gem automatically append ‘?=metadata’ to the url that you provide to the constructor, so you don’t have to do it yourself. But even when you do, you won’t break anything.

Associations¶ ↑

Certain Mixcloud objects have associations, for example, a Cloudcast belongs to a User. In most applications, you can call #user_id to retrieve that user. However, if you look at the Mixcloud API, the identifier is actually an URL. So in this gem, you will call

@cloudcast.user_url

to retrieve the API url of the associated user. It does not return a User object, because I believe that it is a responsibility that belongs to your web-app. However, by providing you the API url, it does make it easier for you to build that object.

There is one exception to that rule! A Cloudcast has many Sections, but if you look at the Mixcloud API, it does not treat Section as a resource and they don’t have unique URLs. In this case, when you call:

@cloudcast.sections

For more information regarding associations, check out the documentation below.

Resources¶ ↑

Most of the methods are named after the JSON data retrieved from the Mixcloud API. Here is a list of classes and their methods.

Artist¶ ↑

Mixcloud::Artist contains the following:

Instance methods:

# To return the API url with the most popular, latest, or the hottest cloudcasts for a specific artist

@artist.popular_url
@artist.new_url
@artist.hot_url

Instance variables (defined at initialization):

@name, @key, @slug, @public_url, @api_url

Category¶ ↑

Mixcloud::Category contains the following:

Instance methods:

@category.small_picture_url
@category.large_picture_url
@category.medium_picture_url
@category.thumbnail_picture_url
@category.medium_mobile_picture_url
@category.userpick_users_url 
@category.userpick_cloudcasts_url
@category.users_url
@category.cloudcasts_url

Instance variables (defined at initialization):

@name, @format, @public_url, @api_url, @key, @slug

Cloudcast¶ ↑

Mixcloud::Cloudcast contains the following:

Instance methods:

@cloudcast.medium_picture_url
@cloudcast.extra_large_picture_url
@cloudcast.large_picture_url
@cloudcast.small_url
@cloudcast.medium_mobile_picture_url
@cloudcast.thumbnail_picture_url
@cloudcast.listeners_url
@cloudcast.similar_url
@cloudcast.favorites_url
@cloudcast.comments_url
@cloudcast.sections
@cloudcast.tag_urls

Instance variables (defined at initialization):

@listener_count, @name, @public_url, @api_url, @description, @updated_time, @play_count, @comment_count, 
@percentage_music, @key, @created_time, @audio_length, @slug, @favorite_count, @user_url

Association: A Cloudcast has many Sections:

@cloudcast.sections    # returns an array of Section objects. See Section for its attributes

A Cloudcast has many Tags:

@cloudcast.tag_urls    # returns an array of api-urls of tags (as string) associated with the cloudcast

A Cloudcast belongs to a User:

@cloudcast.user_url    # returns the api url of the associated user

Tag¶ ↑

Mixcloud::Tag contains the following:

Instance methods:

# To return the API url with the most popular, latest, or the hottest cloudcasts with a specific tag

@tag.popular_url
@tag.new_url
@tag.hot_url

Instance variables (defined at initialization):

@public_url, @api_url, @name, @key

Track¶ ↑

Mixcloud::Track contains the following:

Instance methods: # To return the API url with the most popular, latest, or the hottest cloudcasts featuring a specific track

@track.popular_url
@track.new_url
@track.hot_url

Instance variables (defined at initialization):

@public_url, @api_url, @name, @key, @slug, @artist_url

Associations: A Track belongs to an Artist:

@track.artist_url     # returns the api url of the associated artist

User¶ ↑

Mixcloud::User contains the following:

Instance methods:

@user.medium_picture_url
@user.extra_large_picture_url
@user.large_picture_url
@user.small_url
@user.medium_mobile_picture_url
@user.thumbnail_picture_url
@user.feed_url
@user.playlists_url
@user.comments_url
@user.followers_url
@user.favorites_url
@user.following_url
@user.cloudcasts_url
@user.listens_url

Instance variables (defined at initialization):

@username, @name, @cloudcast_count, @following_count, @public_url, @api_url, @listen_count, @key,
@follower_count, @favorite_count, @updated_time, @created_time, @city, @biog, @country

Search¶ ↑

Mixcloud::Search contains the following:

Class methods:

Mixcloud::Seach.find_artist(string)
Mixcloud::Seach.find_cloudcast(string)
Mixcloud::Seach.find_user(string)
Mixcloud::Seach.find_tag(string)

Section¶ ↑

Mixcloud::Section contains the following:

When you call

@cloudcast.sections

, it creates an array of Sections. Each section has the instance variables defined:

@track_url, @position, @start_time, @section_type

License¶ ↑

Copyright © 2012 Alex Fong. Release under MIT license. See the attached License file.