Unicircles API Documentation

This document provides examples of basic REST API interactions using HTTP and JSON.

Contents

      Category Name(Unicircles)             Category ID
      ======================================================= 
      ToMeet
      -------------------------------------------------------
            Clubs                                  101
            Match                                  102
      ToWatch
      -------------------------------------------------------
            Movies                                 0
            Videos                                 3
            TV Shows                               9
            TV Episodes                            10
            Actors                                 4
            Directors                              5
      ToListen
      -------------------------------------------------------
            Albums                                 1
            Songs                                  2
            Artists                                6
      ToRead
      --------------------------------------------------------
            Books                                  7
            Writers                                8

/api/account/logout

Retrieving filter info

Below URL retrieves filter of various lists( recommendations list, Wish/todo list and My list). (Authentication required)

• URL:

    - /api/c/filters
  
    - /api/u/{user_id}/gift/filters # for gifts
  
        

• Params:

  -category_id (required)
  -list_id (optional, default = 0, Yoop (Public)) 
    (Any list id whether it is reco list, my list or user list can be supplied )
    Below is the valid list IDS
    - list_id - 0 -> filters for Yoop
    - list_id - 1 -> trendsetters recommended
    - list_id - 2 -> Friends and trendsetters recommended
    - list_id - 3 -> Unicircles and partners recommended
    - list_id - 4 -> My toplist
    - list_id - 5 -> My Wishlist
  -filter_type (optional) [default - 0 (All), 1 (genres),
     2 (times), 3 (locations)] # To control the processing
  -limit (optional) [default - 5] this limit per category.
     sending limit = 0 turns off limit  
  - user_id (required if supplying user list id)       
    

• Sussessfull response example:

  login required if fetching my list, user list or (reco list and list_id > 0)
  Returns in :data field following hash
     { 
       :genres    => array_of_hashes_containing_id_title_and_count,
       :times     => array_of_hashes_containing_id_title_and_count,
       :locations => array_of_hashes_containing_id_title_and_count
     }
     

Retrieving recommendation list

To be used to retrieve the recommendation list for a particular category.Authentication required for list_id > 0

• URL:

/api/c/recos

• Params:

  - category_id (required)
  
  - list_id (optional, default = 0, Yoop (Public)) 
    [ list_id should belong  /api/c/lists/reco list_ids]
    
  - genre_id (optional, default = 0, All Genres)
  
  - time_id (optional, default = 0, All Time Periods)
  
  - location_id (optional, default = 0, All Locations)
  
  - sort_id (optional, default = 0, Sort on Yoo Rating DESC)
  
  - offset (optional, default = 0)
  
  - limit (optional, default = 5)
  
  - response (optional, See the response group for details)
  
  - pp (optional, 0/1. default 0)
       Pass this value to force us to return perfect prospect matching the age group of current user
       Valid only for loged in user.
       
  - age (optional, its an alternative to 'pp' params.)
        Use this when you want a specific age range e.g &age=25:30
        Valid for logged in user and guest user.
        
  - cc (optional, valid values includes ISO 3166-1 country code)
       if supplied it will return the items popular in that country
       
  NOTE:- params 'pp' and 'age' is only valid for prospects i.e for new friends and new dates.
    

• Successful response example

  Returns in :data field following hash
     { :items => [..], # array of hashes containing
                       #   :id, :title, :info, :rating, :rank, :genres,
                       #   :img_url, :yoo_url, :ext_url, :buy_url,
                       #   :who_recommends 
                       # genres is array of hashes of id and title
                       # who_recommends is array of user hashes(id, first_name and rating) who recommends/rated this item
       :item_count => total_item_count # Total Item Count For Param Settings
       :page => { 
         :offset => page_offset,
         :limit => page_limit,
         :is_first_page => true_if_first_page,
         :is_last_page => true_if_last_page 
        }
      }
  

Retrieving gift ideas

Below URL retrieves gift ideas for a user and for a praticular category(Authentication required)

• URL:

    /api/u/{user_id}/gift/recos
        

• Params:

  - category_id (required)
  - user_id (required, as a part of the url)
  - genre_id (optional, default = 0, All Genres)
  - time_id (optional, default = 0, All Time Periods)
  - location_id (optional, default = 0, All Locations)
  - sort_id (optional, default = 0, Sort on Yoo Rating DESC)
  - offset (optional, default = 0)
  - limit (optional, default = 5)      
    

• Sussessfull response example:

  Returns in :data field following hash
    { 
      :items => [..], # array of hashes containing
                      #   :id, :title, :info, :rating, :rank, :genres, 
                      #   :img_url, :yoo_url, :ext_url, :buy_url
                      # genres is array of hashes of id and title
     :item_count => total_item_count # Total Item Count For Param Settings
     :page => { 
       :offset => page_offset, 
       :limit => page_limit, 
       :is_first_page => true_if_first_page, 
       :is_last_page => true_if_last_page 
      }
    }
     

Retrieving My Lists

To retrieve my list (Toplist, ToDo/wish list and gift list) items below URL is used. Here my lists referes to personalized data of logged in user, so authentication is required.

• URL:

    -   /api/my/toplist/{category_id}
    -   /api/my/wishlist/{category_id}
    -   /api/my/giftlist/{category_id} [TODO]
        

• Params:

  - category_id (required, as part of the url)
  - genre_id (optional, default = 0, All Genres)
  - time_id (optional, default = 0, All Time Periods)
  - location_id (optional, default = 0, All Locations)
  - sort_id (optional, default = 0, Sort on Yoo Rating DESC)
  - offset (optional, default = 0)
  - limit (optional, default = 5)
  - response (optional, See the response group for details)
    

• Sussessfull response example:

  Returns in :data field following hash
     { :items => [..], # array of hashes containing
                       #   :id, :title, :info, :rating, :rank, :genres,
                       #   :img_url, :yoo_url, :ext_url, :buy_url
                       # genres is array of hashes of id and title
       :item_count => total_item_count # Total Item Count For Param Settings
       :page => { 
         :offset => page_offset,
         :limit => page_limit,
         :is_first_page => true_if_first_page,
         :is_last_page => true_if_last_page }
      }
      

Retrieving user's List

To retrieve list items (Top, ToDo/wish, Gift lists) of any user below URL is used.

• URL:

    /api/u/{user_id}/toplist/{category_id}
    /api/u/{user_id}/wishlist/{category_id}
    /api/u/{user_id}/giftlist/{category_id} [TODO]
  
        

• Params:

  -category_id (required, as part of the url)
  -user_id (required, as the part of the url)
  - genre_id (optional, default = 0, All Genres)
  - time_id (optional, default = 0, All Time Periods)
  - location_id (optional, default = 0, All Locations)
  - sort_id (optional, default = 0, Sort on Yoo Rating DESC)
    To sort ToMeet - valid params are title ASC/DESC
  - offset (optional, default = 0)
  - limit (optional, default = 5)

    

• Sussessfull response example:

  { 
    :items => [..], # array of hashes containing
                    #   :id, :title, :info, :rating, :rank, :genres,
                    #   :img_url, :yoo_url, :ext_url, :buy_url
                    # genres is array of hashes of id and title
    :item_count => total_item_count # Total Item Count For Param Settings
    :page => { 
      :offset => page_offset,
      :limit => page_limit,
      :is_first_page => true_if_first_page,
      :is_last_page => true_if_last_page 
    }
  }
      

Voting a content / items

Below URL is used to submit user vote. These actions add/remove to my list.These actions require authentication

• URL:

    /api/c/vote/tup/{content_id}   [Thumbs Up]
    /api/c/vote/tdn/{content_id}   [Thumbs Down]
    /api/c/vote/del/{content_id}   [Remove]
    /api/c/vote/{value}/{content_id}   [stared rating, value should be 1- 5]
        

• Params:

  - content_id (required, as part of the url) [As provided in the record of any list item]
    

• Sussessfull response example:

  - response['data'] is rating value stored or false if failed
    

Mananing my wishlist

Below URL adds/deletes item to/from my wishlist(aka ToMeet/ToWatch/ToListen/ToRead).(Authentication required)

• URL:

    /api/c/wish/add/{content_id}
    /api/c/wish/del/{content_id}
        

• Params:

  - content_id (required, as part of the url)
  - genre_id (optional, default = 0, All Genres)
  - time_id (optional, default = 0, All Time Periods)
  - location_id (optional, default = 0, All Locations)
  - sort_id (optional, default = 0, Sort on Yoo Rating DESC)
  - offset (optional, default = 0)
  - limit (optional, default = 5)
  - response (optional, See the response group for details)
    

• Sussessfull response example:

  - response['data'] is true or false if failed
     

Retrieving my friends

Below URL returns list of my friends.(Authentication required)

• URL:

    /api/my/friends
        

• Params:

  - limit (optional, defualt is 5)
  
  - offset (optional, defualt is 0)
  
  - order (optional, default is popularity)
    Valid values include below:
    
    - popularity => Sorts friends by popularity
    
    - date => Sorts friends by date added
    
    - taste_similarity => Sorts friends by overall taste similarity
    
    - taste_similarity_watch => Sorts friends by watch taste similarity
    
    - taste_similarity_listen => Sorts friends by listen taste similarity
    
    - taste_similarity_literature => Sorts friends by literature taste similarity
    
    - first_name DESC/ASC => Sorts friends by first name
    
    - last_name DESC/ASC => Sorts friends by last name
    

• Sussessfull response example:

  -response['data'] = {
    items: array_of_list_item, 
    request: request_data_as_with_any_other_list 
  }
    list_item contains following attributes...
    
    :id      => content id(should always be in the form of date_prospect_<id>/friend_prospect_<id>)
    
    :title   => full name of the friend
    
    :rank    => Yoo rank of the friend 
    
    :img_url => Image URL of the friend to get image of the friend
    
    :yoo_url => Detail page URL
    
    :email   => Email address of the friend,
    
    :user_id => Numerical user id on yoopedia database.
    
     

Retrieving user's friends

Below URL returns list of a user, with id = user_id, friends.(Authentication required)

• URL:

    /api/u/{user_id}/friends
        

• Params:

  - user_id (required, as part of the url)
  - Other optional params are same as  friends params
    

• Sussessfull response example:

  -response['data'] = {
    items: array_of_list_item, 
    request: request_data_as_with_any_other_list 
  }
    list_item contains following attributes...
    
     Same as my friends successful response
    
    
     

Search for an item

Below URL retrieves a list of items, friends or dates based on supplied keyword.

• URL:

    /api/c/search
        

• Params:

  - category_id (required)
  - keyword (required) 
  - limit (optional) [default - 5] this limit per category.
     sending limit = 0 turns off limit
  - response (optional, See the response group for details)
    

• Sussessfull response example:

  Returns in :data field following hash
  { 
    :items => [..], # Array of items.The attributes of item depend on response group.
    :item_count => total_item_count # Total Item Count For Param Settings
    :page => { 
     :offset => page_offset,
     :limit => page_limit,
     :is_first_page => true_if_first_page,
     :is_last_page => true_if_last_page 
    }
  }
     

Retrieving details of an item

Below URL retrieves the detail of an item, friend or date based.

• URL:

    /api/c/detail/#{content_id}
        

• Params:

  - content_id (required)
  - tr (optional) true/false, default is false
    Pass this params to retrieve the 'who likes' this item 'also recommends'
    

• Sussessfull response example for category- ToWatch, ToListen or ToRead:

      :id        => content id,
      
      :title     => title of the content
      
      :info      => description of the content
      
      :category  => Category of the contnet(ToWatch, ToListen or ToRead)
      
      :rating    => Youtoo user rating(DEPRICATED)
      
      :rank      => Yoo Rank of the content(DEPRICATED)
      
      :ratings   => Array of Internal and external ratings.
                    [
                      {:name => "#{APP_NAME} Rating", :value => value}, 
                      
                      {:name => "Yoop's Custom Rating", :value => value} 
                      [Only if user is logged in and its available],
                      
                      {:name => "#{APP_NAME} Average Rating", :value => value, :votes => value}, 
                      
                      {:name => 'External Rating', :value => value, :votes => value}, 
                      
                      {:name => 'Imdb/Napter/Youtube Rating', :value => value, :votes => value}
                      [For Movie,actor,director, album, song, video]
                      
                    ]
      
      :ranks     => Array of Unicircles and yoo rank.
                    [
                      {:name => "#{APP_NAME} Rank", :value => value}, 
                      {:name => 'Yoo Rank', :value => value}
                    ]
      
      :genres    => Genres of the content, blank if it is people(actor, director, artist or writer) 
                     
      :img_url   => URL of the content to retrieve its image
      
      :yoo_url   => Detail page URL(Internal use only)
      
      :ext_url   => External link of the content i.e related link on imdb.com, amazon.com, 
                    youtube.com or napster.com
                    
      :embed_url => Only available for movie or video
      
      :buy_url   => Related buy link on amazon, not available for video
      
      :ply_url   => Playable url - only available for the conents and which are playable
      
      :ply_urls  => Playable urls - only available for the conents and which are playable
                    Its an array of hash as below
                    [
                      {:link => url of source1, :source => name of the source1},
                      {:link => url of source2, :source => name of the source2},
                      {:link => url of source3, :source => name of the source3},
                      ...........
                      ...........
                    ]
                    
      :playble   => Content is playable or not
      
      :reviews   => reviews of the content written by Unicircles user.(if params 'reviews'= true)
                    [
                      :reviewer => {:id, :title, :img_url, :user_id}
                      :review   => {:id, :description, :created_at, 
                        :content_type => :content_title, :content_image)
                      }
                    ]
                    
      :who_recommends  => List of trendsetters (id, title, img_url) who recommends this(if params tr is true)
      :also_recommends => List of contents (id, title, img_url) recommended by "who_recommends/trendsetters" (if params tr is true)
      
      :wishlist        => true/false, indicates if the item is user's todo list
      
      :my_rating       => Indicate what is my current rating (0 - 100)
      
      :actors          => List of actors(title, id), [Only for movies]
      
      :directors       => List of directors(title, id), [Only for movies]
      
      :songs           => List of songs in the album[Only for album]
      
      :album           => Album of the song[Only for song]
      
      :music_artists   => List of artists(title, id)[For song and album]
      
      :authors         => List of authors(title, id)[Only for book]
      
      :episodes        => List of TV serie episodes(title, id)[Only for Tv serie]
      
      :series          => Name of TV serie(title, id)[Only for TV Episode]
      
      :movies         => List of movies(title, id) actor/director participated in [Only for actors/directors]
      
      :books          => List of books (title, id) the writer has written [Only for writers]
      
      :albums         => List of albums (title, id) the artist is related to
      
     

• Sussessfull response example for category- ToMeet:

      :id                 => content_id
      
      :title              => Full name 
      
      :first_name         => First name
      
      :last_name          => Last name
      
      :about              => About the user(what he/she has provided about him/her self)
      
      :trivia             => Complied user's info
                            (E.g- # First name is Age years old, lives in Metro Area (Country), and speaks Language. 
                                  # His / Her Yoop Rank is N and Trendsetter Rank is M. (IF AVAILABLE:) He/She likes ZZZ, has XXX, 
                                  # and wants YYY.)
      :gender             => Gender
      
      :wants              => Wants
      
      :has                => Has
      
      :likes              => Likes
      
      :date_of_birth      => Date of birth
      
      :member_since       => Since when the user is on Unicircles
      
      :languages          => Primary and secondary language of the user
      
      :cities             => Metro cities of the user
      
      :category           => ToMeet
      
      :video_url          => Profile video URl uploaded by user itself

      :popularity         => User's popularity on Unicircles
      
      :trendsetter_name   => Trendsetter name of the user(TrendMaster, TrendSetter or TrendSeeker)
      
      :trendsetter_rank   => Trendsetter rank on Unicircles
      
      :trendsetter_rating => Trendsetter rating/score of the user
      
      :rank               => Yoo rank of the user
      
      :img_url            => Image URL of the user
      
      :email_address      => Email address of the user
      
      :user_id            => User ID of the user
      
      :friends            => list of user friends
      
      :friendship         => Indicates friendship status of user, possible values are
                             - accepted - means both are friend
                             - invited  - means you have invite him/her
                             - invite   - means he/she is not your friend, so you can send invite
                             - accept   - means user has invited you and you need to accept this request.
      
      :reviews            => list of reviews written by the user.
      
     

Retrieving user's newsfeed

Below URL retrieves my newsfeed/update(Authentication required)

• URL:

    /api/u/{user_id}/news
        

• Params:

  - user_id (required)      
    

• Sussessfull response example:

  {
    :item =>{
      :title => name-of-title,
      :yoo_url  => detail-page-url-or-nil,
    },
    :action => name-of-the-action-or-nil,    
    :doer => {
      :name => action-doer-name,
      :yoo_url  => detail-page-url,
      },
    :when => time-of-action
  }
     

Invite a friend.

Below URL sends an invitation mail to external user .Here external users means- user who is not using Unicircles (Authentication required)

• URL:

    /api/u/invite
        

• Params:

  - email (required, as part of the url)
  - message (optional)
    

• Sussessfull response example:

  - response['data'] is invitaion message 
     

Find a user exists or not

Below URL is used to find the existence of a user

• URL:

    /api/u/exists [DEPRICATED]
    /api/account/exists [NEW]
        

• Params:

  - username/login or email address(required, as part of the url)
  
    

• Sussessfull response example:

  - response['data'] is either true/false
    

Add a friend.

Below URL adds a friend to the friendlist of current user (Authentication required)

• URL:

    /api/u/add
        

• Params:

  - friend_id (required, as part of the url, do not confuse this with content_id it should be the user_id)
  - message   (optional, so that invitee can identify inviter)
  - resend    (optional(true/false), to resend an invite.)
    

• Sussessfull response example:

  - response['data'] is invitaion message 
     

Response Group

We have grouped the result set into the three listed below. To retrieve the response group of your choice just append response=small/medium/large in the URL including other parameters. A valid resposne group can be supplied while retrieving any list items.

• Small:

    id, title, category
        

• Medium

  id, title, info, category, rating, rank, img_url, yoo_url, new_release, pre_release
    

• Large:(default response group)

   id, title, info, tooltip, category, rating, rank, genres, img_url,
   yoo_url, ext_url, buy_url, ply_url, playble, new_release pre_release
     

Sending a message to a friend

Below URL is used to send a message to a friend (Authentication required)

• URL:

    /api/u/message
        

• Params:

  - recipient_id (required, as part of the url) [should be a valid user_id not content_id]
  
  - subject (optional)
  
  - body (required) 
    

• Sussessfull response example:

  - response['data'] is custom message delivery message
    

Resetting a user's password

Below URL resets the password of the a user whose email address or username/login is passed as an argument.

• URL:

    /api/u/forget_password [DEPRICATED]
    /api/account/forgot_password [NEW]
        

• Params:

  - email/username (required, as part of the url)
    

• Sussessfull response example:

  - response['data'] is respose messages
     

Recommend a content / items

Below URL is used to recommend a content to a friend.This actions requires authentication

• URL:

    /api/c/recommend/{content_id}
        

• Params:

  - content_id (required, as part of the url) [As provided in the record of any list item]
  - recipient_id (required, as part of the url)
  - message (optional, if you want to attach message)
    

• Sussessfull response example:

  - response['data'] is notification
    

Search for an item in externl/partners database

Below URL retrieves a list of items matching a keyword in our partners database.

• URL:

    /api/c/search/external
        

• Params:

  - category_id (required)
  - keyword (required)
    

• Sussessfull response example:

  Returns in :data field following hash
  { 
    :item_count => total_item_count,
    :category   => ToWatch/ToRead/ToListen,
    :items      => [
                      {:title, :description, :source_id}
                   ]
  }
     

Import an item from externl/partners database

Below URL imports an item our partners database. NOTE:- This a asynchorous process ie the import will be a realtime action, but it will accept request and later it will import item, optionally it will be added item to you list if specified

• URL:

    /api/c/import
        

• Params:

  - category_id (required)
  - source_id (required)
  - list (optional) [valid values - toplist/wishlist]
    If passed the imported item will added to user's list(toplist/wishlist)
    But for this Authentication is required.
    

• Sussessfull response example:

  - response['data'] is respose messages
     

Retrieving image of an item

Below URL retrieves the image of an item.

• URL:

    /api/c/image/#{content_id}
        

• Params:

  - content_id (required)
  - size (optional) , default is large, same size what we show on site show page.
    Valid sizes are: small, medium, thumbnail, large and xlarge
    

• Sussessfull response example

        {:img_url => 'url of the image', :size => size of the image, :id => content id}
      

How do you compare? (Mix & Match)

Below URL returns the exact information what we have on our 'Mix & Match' page, To get this record one need to be Authenticated.

• URL:

    /api/u/#{user_id}/compare
        

• Params:

  - user_id (required)
    

• Sussessfull response example:

  - response['data'] contains below:
  {
    :both_likes => [
      {
        :type=> content_type,:img_url => image URL of content, 
        :title => Title of the content, :id => content_id
      },
      ................
      ................
    ]
    :both_dislikes => [
      {
        :type=>content_type,:img_url => image URL of content, 
        :title => Title of the content, :id => content_id
      },
      ................
      ................
    ]  
    :friend_recommends => [
      {
        :type=>content_type,:img_url => image URL of content, 
        :title => Title of the content, :id => content_id
      },
      ................
      ................
    ]                    
  }
     

List modification time

The below URL return time stamp when list (toplist or wishlist) were last updated by user activity.This action requires Authentication

• URL:

    /api/u/{user_id}/modtime
        

• Params:

  - category_id (required)
  - list (required) either toplist, wishlist, recos or friend
    NOTE: For friend list pass category_id 101.
    

• Sussessfull response example:

  - response['data'] is a integer representation of last modified
     

Retrieving New and Pre release

To retrieve latest items/members, below URL is used. If user is authenticated then it will exclude the item rated or added to wishlist of the logged in user.

• URL:

    -   /api/c/latest?category_id={category_id}
        

• Params:

  - category_id (required, as part of the url)
  - oid (optional), if passed it will return personalized new and pre releases
  - offset (optional, default = 0)
  - limit (optional, default = 5)
  - filter (optional), possible options - new, trending and upcoming
    Default value is all which we need not to pass.
    

• Sussessfull response example:

  Returns in :data field following hash
     { :items => [..], # array of hashes containing
                       #   :id, :title, :info, :rating, :rank, :genres,
                       #   :img_url, :yoo_url, :ext_url, :buy_url
                       # genres is array of hashes of id and title
       :item_count => total_item_count # Total Item Count For Param Settings
       :page => { 
         :offset => page_offset,
         :limit => page_limit,
         :is_first_page => true_if_first_page,
         :is_last_page => true_if_last_page }
      }
      

Creating temporary account

Below URL creates temporary user account which is mainly used for pre login swoop.

• URL:

    /api/account/temp
        

• Params:

  - None, no any params are required
    

• Sussessfull response example:

  - response['data'] => {:message => 'Account created', :id => user_id, :email => email_of the user}
     

Creates swoop for pre login

Below URL is used to create swoop for pre login page. NOTE:- Bedefault swoop is created from 'yoop' but if we pass 'sid' params which is user_id of inviter then swoop is created from inviters wish and toplist items.

• URL:

    /api/swoop/create
        

• Params:

  - oid (required) - This is email address of temporary user
  - rid (required) - This is temporary user_id, see here how to create temporary account
  - sid (optional) - This will be user_id of inviter, this is required if the user follows invite link to sign up
    But for this Authentication is required.
    

• Sussessfull response example:

Returns in :data field following hash
 { 
   :token => token of the swoop which is used when accepting or removing swoop items,
   :sender => {:name => sender name, :id => sender content id },
   :books => [
      {
        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
        },
        
      {
        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ],
                 
   :movies => [
      {
        :title => 'title of movie', :id => content_id of movie, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of movie', :id => content_id of movie, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of movie', :id => content_id of movie, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ],      
   :albums => [
      {
        :title => 'title of album', :id => content_id of album, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of album', :id => content_id of album, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of album', :id => content_id of album, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ],     
   :tvseries  => [
      {
        :title => 'title of tvseries', :id => content_id of tvseries, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of tvseries', :id => content_id of tvseries, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      { 
        :title => 'title of tvseries', :id => content_id of tvseries, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ]  
   :videos => [
      {
        :title => 'title of video', :id => content_id of video, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of video', :id => content_id of video, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of video', :id => content_id of video, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
  ]                                                        
 }
     

Send swoop invite to a user

Below URL is used to send a swoop invite to a user

• URL:

    /api/swoop/invite
        

• Params:

  - oid (required) - This is email address of logged in user
  - rid (required) - Invitee's user_id
  - mtitle (optional) - Title of swoop message
  - mbody (optional)  - Body text of the swoop message
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "Swoop invite sent to xxx."
     }
     

Add swoop item to wishlist

Below URL is used to add a swoop item to wishlist

• URL:

    /api/swoop/wish
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - swoop_id (required) - This is the id of swoop
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "XXX added to you todo list",
       :title => title of the swoop item,
       :my_rating => my rating,
       :wishlist => true/false (whether in my wishlist or not),
       :swoop_id => swoop ID,
       :id => content ID
     }
     

Recommend a swoop item

Below URL is used to recommend a swoop, recommending a swoop item adds that item to user's toplist with 4 start rating

• URL:

    /api/swoop/recommend
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - swoop_id (required) - This is the id of swoop
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "XXX added to you todo list",
       :title => title of the swoop item,
       :my_rating => my rating,
       :wishlist => true/false (whether in my wishlist or not),
       :swoop_id => swoop ID,
       :id => content ID
     }
     

Accept all swap items

Below URL is used to accept all swoop items.

• URL:

    /api/swoop/accept
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - token (required) - This is the token received when creating or viewing swoop
  - type (optional) - This is type of swoop (eg movie, book, album tvseries or video)
    NOTE: If type is not provided then all swoop item is added to wishlist.
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "Added nn items to your todos list"
       :type     => [
                      {
                        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
                        :wishlist => true/false, :swoop_id => swoop id
                      },
                      
                      {
                        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
                        :wishlist => true/false, :swoop_id => swoop id
                      },
                      
                      {
                        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
                        :wishlist => true/false, :swoop_id => swoop id
                      },
                      ....................
                      ....................
                      
                     ],
      :count => number of item added
     }
     NOTE: Here type can be movies, books, albums, tvseries or videos, it will be plural of type we pass as params.
     

Remove all swap items of a type or a particular swap item

Below URL is used to remove all swap item of a type or a particular swap item (movie, book, album etc).

• URL:

    /api/swoop/remove
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - token - This is the token received when creating or viewing swoop
  - type  - This is type of swap (eg movie, book, album, tvseries or video)
  - swoop_id - Swoop ID of the content
    For this Authentication is required.
    NOTE: We need not to provide token and type when providing swoop_id, if we provide swoop_id then that particular swoop
    will be removed. And if we want to remove all swoop of a type then we need to provide token and type.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "Removed nn items to your todos list"
       :type     => [
                      {
                        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
                        :wishlist => true/false, :swoop_id => swoop id
                      },
                      
                      {
                        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
                        :wishlist => true/false, :swoop_id => swoop id
                      },
                      
                      {
                        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
                        :wishlist => true/false, :swoop_id => swoop id
                      },
                      ....................
                      ....................
                      
                     ]
     }
     NOTE: Here type can be movies, books, albums, tvseries or videos, it will be plural of type we pass as params.
     

Finishing a swoop

Below URL is used to finish a swoop

• URL:

    /api/swoop/done
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - token (required) - This is the token received when creating or sending swoop
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "Added nn items to your todos list"
     }
     

Getting swoop messages

Below URL is used to get swoop messages which is used view swoop items

• URL:

    /api/swoop/messages
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - pending (optional) - If passed if will only return un read swoop messages
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     :messages => { 
       :subject  => "Title of the swoop message",
       :body => swoop message,
       :token => swoop token used to view, accept or declince swoop,
       :created_at => when swoop was sent,
       :sender => {:name => sender name, :id sender content id}
     }
     

View swoop

Below URL is used to view swoop and its items

• URL:

    /api/swoop/show
        

• Params:

  - oid (required) - This is email address of temporary user
  - token (required) - swoop token
    For this Authentication is required.
    

• Sussessfull response example:

Returns in :data field following hash
 { 
   :token => token of the swoop which is used when accepting or removing swoop items,
   :sender => {:name => sender name, :id => sender content id },
   :books => [
      {
        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
        },
        
      {
        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of book', :id => content_id of book, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ],
                 
   :movies => [
      {
        :title => 'title of movie', :id => content_id of movie, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of movie', :id => content_id of movie, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of movie', :id => content_id of movie, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ],      
   :albums => [
      {
        :title => 'title of album', :id => content_id of album, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of album', :id => content_id of album, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of album', :id => content_id of album, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ],     
   :tvseries  => [
      {
        :title => 'title of tvseries', :id => content_id of tvseries, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of tvseries', :id => content_id of tvseries, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      { 
        :title => 'title of tvseries', :id => content_id of tvseries, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
    ]  
   :videos => [
      {
        :title => 'title of video', :id => content_id of video, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of video', :id => content_id of video, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      
      {
        :title => 'title of video', :id => content_id of video, :my_rating => my rating, 
        :wishlist => true/false, :swoop_id => swoop id
      },
      ....................
      ....................
                  
  ]                                                        
 }
     

Decline swoop

Below URL is used to decline all item of a swoop.

• URL:

    /api/swoop/decline
        

• Params:

  - oid (required) - This is email address of user, if using it for pre login then pass temporary user's email address
  - token (required) - This is the token received when creating or viewing swoop
    For this Authentication is required.
    

• Sussessfull response example:

    Returns in :data field following hash
     { 
       :message  => "Successfully declined swoop",
       :count => number of item declined
     }
     

Accept a friend/club request.

Below URL is used to accept a club request, for this (Authentication is required)

• URL:

    /api/u/accept
        

• Params:

  - friend_id (required, as part of the url, do not confuse this with content_id it should be the user_id)
    

• Sussessfull response example:

  - response['data'] is a notification
     

Reject a friend/club request.

Below URL is used to reject a club request, for this (Authentication is required)

• URL:

    /api/u/reject
        

• Params:

  - friend_id (required, as part of the url, do not confuse this with content_id it should be the user_id)
    

• Sussessfull response example:

  - response['data'] is a notification
     

Remove a friend/club member from your list.

Below URL is used to remove a club member from your list, for this (Authentication is required)

• URL:

    /api/u/remove
        

• Params:

  - friend_id (required, as part of the url, do not confuse this with content_id it should be the user_id)
    

• Sussessfull response example:

  - response['data'] is a notification
     

Mapping external account with Unicircles account.

Below URL is used to link your external account with Unicircles account. Once you have linked your account with Unicircles account then you can login with external account. For this (Authentication is required)

• URL:

    /api/account/map
        

• Params:

  - eid (required, external user ID)
  - source (required, Source name eg - facebook)
    

• Successful response example:

  - response['data'] is a notification
     

Trending with Friends and Influencers

To retrieve the trending items among the friends and influencers, below URL is used. Authenticated is required.

• URL:

    -   /api/c/trending?category_id={category_id}&oid={email address}
        

• Params:

  - category_id (required, as part of the url)
  - oid (required)
  - offset (optional, default = 0)
  - limit (optional, default = 5)
  - filter (optional), possible options - new and upcoming
    

• Sussessfull response example:

  Returns in :data field following hash
     { :items => [..], # array of hashes containing
                       #   :id, :title, :info, :rating, :rank, :genres,
                       #   :img_url, :yoo_url, :ext_url, :buy_url
                       # genres is array of hashes of id and title
       :item_count => total_item_count # Total Item Count For Param Settings
       :page => { 
         :offset => page_offset,
         :limit => page_limit,
         :is_first_page => true_if_first_page,
         :is_last_page => true_if_last_page }
      }