Skip to content

Latest commit

 

History

History
110 lines (75 loc) · 4.9 KB

README.md

File metadata and controls

110 lines (75 loc) · 4.9 KB
Raw

Hypem Ruby Gem travis Code Climate#

Introduction

This is an unoffical Ruby gem for the Hype Machine read-only API. It currently only supports Ruby >= 1.9.2.

Usage

Playlist

The Playlist object is the root of the Hypem API. Each Playlist has an array of Hypem::Track's accessed via the tracks attribute. Pagination is supported with the .next_page and .prev_page, page(num) methods.

Querying

General playlists can be accessed using the following methods. The last argument to each method is the desired page (default 1).

  • Hypem.playlist.artist('artist_name') --- latest tracks from a given artist

  • Hypem.playlist.blog('blog_name') --- latest tracks from a given blog name

  • Hypem.playlist.search('query_string') --- tracks matching string

  • Hypem.playlist.tags(['tag_name','electro','indie']) --- tracks matching tags. The API warns against combining too many different tags

  • Hypem.playlist.popular --- the most popular tracks over a certain timeframe or set. It accepts the following filters:

    • '3day' default --- most popular over last 3 days
    • :lastweek --- most popular over last week
    • :noremix --- most popular non-remixed tracks over last 3 days
    • :artists --- most popular artists' tracks over last 3 days
    • :twitter --- most popular tweeted tracks over last 3 days

  • Hypem.playlist.latest --- the latest posted tracks. It accepts the following filters:

    • :all default --- all tracks, regardless of repost status
    • :fresh --- only first posted tracks
    • :noremix --- only non-remixed tracks
    • :remix --- only remixed tracks

Misc.

  • Hypem.playlist.new_from_tracks([hypem_track1,hypem_track2]) --- create a custom playlist from an array of Hypem::Track's

User

Users can be accessed via Hypem.user('username') and have various methods:

General Methods

  • user.get_profile updates the user object with the following attributes: full_name, location, image_url, followed_users_count, followed_items_count, followed_sites_blog, and followed_queries_count

  • user.friends retrieves the user's friends as an array of Hypem::User objects

  • user.favorite_blogs retrieves the user's favorite blogs as an array of Hypem::Blog objects

Playlist Methods

Hypem::User offers several methods for accessing a particular user's personalized playlists:

  • user.loved_playlist --- a user's loved tracks

  • user.obsessed_playlist --- a user's obsessed tracks

  • user.feed_playlist --- a user's tracks from all followed entities

  • user.friends_favorites_playlist --- a user's friends' favorited tracks

  • user.friends_history_playlist --- tracks from a user's friends' listening histories

Blog

Blogs can be retrieved using a blog's unique id via Hypem.blog(1234) and have the following methods:

  • blog.get_info -- retrieves extended information about a blog and sets blog_image, blog_image_small, first_posted, followers, last_posted, site_name, site_url, total_tracks, and id

Track

Tracks can be initialized using a known media_id via Hypem.track('media_id') and synced using the get method on any instance. Depending on the playlist type, some tracks may have more detailed attributes than other.

An example track object inspection is as follows:

@media_id="1jsw9",
@artist="Hot Chip",
@title="Flutes",
@date_posted=#<DateTime: 2012-06-08T16:57:00-07:00 ((2456087j,86220s,0n),-25200s,2299161j)>,
@site_id=16116,
@site_name="the untz and the indie",
@post_url="http://theuntzandtheindie.com/2012/06/08/hot-chip-party/",
@post_id=1835105,
@loved_count=9050,
@posted_count=33,
@thumb_url="http://static-ak.hypem.net/images/albumart0.gif",
@thumb_url_large="http://static-ak.hypem.net/images/blog_images/16116.png",
@time=425,
@description="Today’s Indie: If I Was Your Girlfriend (Hot Chip Cover) / Prince /// Motion Sickness / Hot Chip /// Flutes / Hot Chip So the indie extraordinaire and goddess of all things awesome is out of town up in the Pac NW gettin silly and listening to dAHnce music",
@itunes_link="http://hypem.com/go/itunes_search/Hot%20Chip"

Track Favorites

The people who liked a track can be retrieved via Hypem::TrackFavorites('trackid') or track.favorites and synced using the get method.

Their pagination is supplied via the same methods as the Hypem::Playlist ones, and they also accept the desired page as the last argument at initialization : Hypem::TrackFavorites('trackid', page)

The Hypem::Users present in each page can be retrieved via the users instance method

TODO

  • Blogs with given tag
  • Authenticated Requests
  • Favorite a track
  • Log Playback