Unicircles API Documentation

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


Contents

API Overview

This document is intended for programmers who want to write code to interact with Unicircles using HTTP and JSON.


This document assumes that you understand the general idea of a REST API, and that you're familiar with the Unicircles GUI.


If you're using a UNIX system and you want to try the examples in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful.


As a Unicircles user, user has three lists at their disposal.
  • Recommendation list: Are the collection of recommended things/people user may want to watch, meet, listen or read.These recommendations are always based on user's taste and social similarity and which are not known by the user ie not in user's ToDo or Toplist. To get the list of Unicircles recommended items we use this API call.
  • ToDo list: User's ToDo list (a.k.a - ToWatch, ToListen, ToMeet or ToRead List) are the collection of things/people user wants to watch, meet, listen to or read. An item is added to user's ToDo List if he/she clicks on Add to ToDo list (ToWatch, ToListen, ToMeet or ToRead List) To get user's ToDo List we use this API call.
  • Toplist: User's Toplist are collection of best ranked movies, people, music and books. An item is added to user's Toplist when he/she thumbs up/down or recommends/rates/Adds to Toplist. To get user's Toplist List we use this API call.

Before going through the further manual, please have a look on available categories on Unicircles
      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

Authentication

The REST API has a number of methods that require user authentication to access personalized data. For instance, functionality on Unicircles available to logged in users, such as users recommendation list, wish/todo list, friends list and newsfeed are protected through the API which requires authentication. The Search API has no notion of accounts and therefore requires no authentication.


Authentication on Unicircles is REST Based so developer needs to provide parameter oid (here oid refers to email address of current/logged in user) with every action that requires authentication.


  • Login URL:
  •   #  /api/account/login?oid=<oid value> ifoid is register with us
      #  /api/account/login?oid=<oid value>&uid=<user id/email address at Unicircles>&pwd=<password>
      # [password is needed once to establish link between oid and uid 
      # (if authentication is succesful, next time authentication can be done only by oid)
      # response['data'] is a hash like the following
      {
        "return_to":null,
        "user":{
          "id":1,
          "name":"Imdad Ali Khan",
          "code": "<encrypted password>",
          "email": "<email address>"
          
        },
        "notice":"user logged in successfully"
      }
      
  • Logout URL:
/api/account/logout

Sign up

  • To construct Signup Form
  • URL
      /api/account/signup/fields
      # Returns array of Field Data
      # Field Data is an array of 6 elements
      # [title, attribute_name, input_type, default_value, optional_field, required_field ]
      # optional_field
      #   For select field field it contains the action_name
      #     /api/account/signup/options/{action_name}
      #     will return the options for the field as an array of arrays
      #   For text field it contains the info like what should be the format of the text field
      #   like minimum 10 characters long etc
      # The Date of Birth is an exception
      #   the attribute_name is an array of attribute names
      #   the optional_field contains the array of action names corresponding to each 
      #   attribute name
            
  • Signup Select Options
  • For select options you can query and you will get array of options each option is an array of two elements. first is the name (anchor tag) and second is the value attribute

      /api/account/signup/options/years
      /api/account/signup/options/months
      /api/account/signup/options/dates
      /api/account/signup/options/genders
      /api/account/signup/options/educations
      /api/account/signup/options/languages
      /api/account/signup/options/countries
        - params: grouped=true
        - params: html=true [will return select HTML, applied only when grouped=true]
        This will retrun countries grouped by Hemisphere
      /api/account/signup/options/cities
        - params: grouped=true
        - params: html=true [will return select HTML, applied only when grouped=true]
        This will retrun cities grouped by Hemisphere
        
  • To get terms and conditions of the page
  •   /api/account/signup/options/terms
      (this will return the terms and conditions "as a html string".
    
  • Signup Form Submission
  • URL
    /api/account/signup
    Params
      # u - user attributes as a hash
      # on successful signup (the user is automatically authenticated)
    
    Successful Response example:
        {
          "data":{
            "user":{
                "name":"abcd ef",
                "id":24
              },
            "notice":"user signup successful",
            "return_url":null
          },
          "request":{
            "params":{
              "u":{
                "date_of_birth(2i)":"12",
                "date_of_birth(3i)":"25",
                "password_confirmation":"12345",
                "gender":"male",
                "terms_of_service":"1",
                "first_language":"english",
                "first_name":"abcd",
                "country2_id":"1",
                "city_id":"238",
                "password":"12345",
                "login":"abcdef11",
                "last_name":"ef",
                "date_of_birth(1i)":"1980",
                "email_address":"abcdef123@ef.com"
              }
            },
          "errorno":0,
          "id":1222
          }
        }
    
    Unsuccessful Response example:
        {
          "data":[
              "Please enter another email address. 'abcdef123@ef.com' is already taken",
              "Please enter another username. 'abcdef11' is already taken"
            ],
          "request":{
            "params":{
              "u":{
                "date_of_birth(2i)":"12",
                "date_of_birth(3i)":"25",
                "password_confirmation":"12345",
                "gender":"male",
                "terms_of_service":"1",
                "first_language":"english",
                "first_name":"abcd",
                "country2_id":"1",
                "city_id":"238",
                "password":"12345",
                "login":"abcdef11",
                "last_name":"ef",
                "date_of_birth(1i)":"1980",
                "email_address":"abcdef123@ef.com"
              }
            },
            "errorno":1,
            "id":1221
          }
        }
    

Retrieving availabe categories

  • Unicircles (Basic)
  • /api/c/categories
  • Unicircles (Becks version)
  •   - /api/c/categories?becks=true
      
      or(DEPRECATED VERSION)
      
      - /api/c/becks_categories
        
  • Unicircles(Gift)
  •   - /api/u/gift/categories
        

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
        
        
         

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
        

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
         

To retrieve the trending items among the friends and critics, 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 }
          }