Retrieve Super Fans

From KickApps Documentation

Overview

This method returns a list of "Super Fans" for a given location. "Super Fans" are fans that have the most number of badges for a given location. This method will have a parameter that limits the total number of results to a user-defined value.

Request URL

http://api.kickapps.com/rest/mostbadged/users/get/{as}

Request Parameters

Required

• as - The site Id to search. as is unique for each of the affiliate's sites.
• location – A location identifier that corresponds to a page / area within the community. For this iteration of the API it is assumed that Client will handle creation of these identifiers in their existing CMS system.

Optional

• callback. String. Optional. The name of your JavaScript callback function.
• pgNum. The current page number in the search results. For your first call, set pgNum to "1". For subsequent calls, set pgNum to the page you want to display. If not provided, this value is defaulted to 1.
• pageSize. The number of results to display on each page. Max pageSize is "1000". If not provided, this value is defaulted to 10.

Response

Note: if callback is provided as an optional argument, the results illustrated below will be returned within the callback string provided for execution of a JavaScript function; e.g. callback=”MyCallbackFunc” will return something similar to:

MyCallbackFunc({…the success or failure response contained in curly braces you see below…});

Success: {

  "status":1,

  "location":"XXXX",
  "totSize":"10",
  "superFans":[
     {
        "userId":"userId1",
        "username":"joe",
        "pathToPhoto":"",
        "numBadges":6,
        "rank":1,
        "timeLastBadgeEarned":1291873747

     },
     {
        "userId":"userId2",
        "username":"cindy",
        "pathToPhoto":"",
        "numBadges":6,
        "rank":2,

     },
     {
        "userId":"userId3",
        "username":"bob",
        "pathToPhoto":"",
        "numBadges":2,
        "rank":3,
        "timeLastBadgeEarned":1291873747

     }
  ]

Failure: {"status": -1, "errorId": "123", "error": "Error Message"}

Response Fields

• status – 1 on success and -1 on error.
• totSize - number of SuperFans.
• error – A message indicating the error condition
• errorId – A numeric reference to the error condition
• location – A location identifier that corresponds to a page / area within the community. For this iteration of the API it is assumed that Client will handle creation of these identifiers in their existing CMS system.
• totSize - The total number of fans that are returned.
• superFans – This is a list of:
• userId - userIds that correspond to the Super Fans (ranked by total number of badges) for the given location.
• userName – name of the user
• pathToPhoto – avatar photo of user (not the thumbnail)
• rank – Rank of the user for the location. If they’ve not me the criteria, they shouldn’t be returned. If there’s no super fan criteria defined for the location, then this call should return an error.

Error codes:

• 1 = invalid token
• 8 = location cannot be null or blank
• 16 = Invalid pgNum
• 17 = Invalid pageSize
• 20 = location cannot exceed 64 characters
• 25 = pageSize cannot exceed 1000
• 44 = token required

List of KickApps API Calls

Note: Occasionally (and without advanced warning) we modify our API calls by adding new parameters in the response payload. Please keep this in mind when designing your strategy for parsing our responses.