User Info Web Service

The Kongregate User Info API is a Web Service that allows games to retrieve information about players. This information includes friends lists, avatar, level, etc. Note that since the user info web service does not require an API key, it is safe to call from either the client or the server.

Responses will be paginated if necessary, as there is a maximum limit of 500 friends or muted users per response page. One should check the num_pages field to determine if pagination was required for any particular request.

No game is allowed to request the friends list for users who have their profile set to private. If you request this field but don't have permission, it will be returned as an empty array.

GET url: http://www.kongregate.com/api/user_info.json
required params:
  username or user_id: Username/user_id of the user to request information about 
  or
  usernames or user_ids: Request multiple username/user_id information at a time (comma separated, maximum 50 at a time)

optional params:
  page_num: The page of data to request (default 1)
  friends: true if you wish to request a friends list

response fields:
  success: true/false depending on if the request was successful
  error: error code integer, if any
  error_description: error code description string, if any

only if successful:
  page_num: The page number
  num_pages: The total number of pages
  user_id: The user's Kongregate id
  username: The user's username
  private: true if this is a private profile
  friends: An array of usernames of this user's friends (if requested) 
  friend_ids: An array of userids of this user's friends (if requested)
  user_vars: An object which contains user-specific variables-
    level: An integer representing the user's level
    avatar_url: URL to the user's full-sized avatar
    chat_avatar_url: URL to the user's chat-sized (small) avatar
    game_title: Title of the game the user is playing
    game_url: URL of the game the user is playing
    developer: true if the user is a developer
    moderator: true if the user is a moderator
    admin: true if the user is an administrator

Example - Successful 1-page request:

Request: 

http://www.kongregate.com/api/user_info.json?username=ap_u2&friends=true

Response: 

{"friends":["ap_u","KIXEYE","llbundle","anthony"],"muted_users":[],
"friend_ids":[1047195,5235025,3903986,2090],"muted_user_ids":[],
"user_id":2295077,"username":"ap_u2","private":false,"page_num":1,"num_pages":1,
"success":true,"user_vars":{"username":"ap_u2","age":26,"level":2,"points":54,
"avatar_url":"http://cdn3.kongregate.com/assets/avatars/defaults/bug.jpg",
"chat_avatar_url":"http://cdn3.kongregate.com/assets/avatars/defaults_chat_sized/bug.jpg",
"curator":false,"developer":false,"moderator":false,"forum_moderator":false,"admin":false,
"gender":null,"game_title":"Backyard Monsters",
"game_url":"http://www.kongregate.com/games/KIXEYE/backyard-monsters"}}

Example - Multiple user info request, no friends.

If you are intending to load lots of user information (for example, loading the avatar URLs for all of a user's friends), you should group them together with this method to avoid long load times or timeouts due to making lots of requests. Some users will have hundreds of friends. Note that the "success":true only occurs for user_id requests, not username requests.

Request: 

http://www.kongregate.com/api/user_info.json?user_ids=1,2

Response: 

{"success":true,"users":[{"friends":[],"muted_users":[],"friend_ids":[],"muted_user_ids":
[],"user_id":1,"username":"jimgreer","private":false,"page_num":1,"num_pages":1,
"success":true,"user_vars":{"username":"jimgreer","level":46,"points":14417,
"avatar_url":"http://cdn1.kongregate.com/user_avatars/0000/0001/k.png?4424-op",
"chat_avatar_url":"http://cdn1.kongregate.com/user_avatars/0000/0001/avatar_atlas3_chat.png?4424-op",
"curator":true,"developer":false,"moderator":true,"forum_moderator":true,"admin":true,
"gender":"Male","game_title":"Call of Gods","game_url":"http://www.kongregate.com/games/callofgods/call-of-gods"}},
{"friends":[],"muted_users":[],"friend_ids":[],"muted_user_ids":[],"user_id":2,"username":"emily_greer",
"private":false,"page_num":1,"num_pages":1,"success":true,"user_vars":{"username":"emily_greer",
"age":37,"level":21,"points":3057,"avatar_url":"http://cdn1.kongregate.com/user_avatars/0000/0002/Anex.png?8917-op",
"chat_avatar_url":"http://cdn3.kongregate.com/user_avatars/0000/0002/Anex_chat.png?8917-op",
"curator":true,"developer":false,"moderator":true,"forum_moderator":true,"admin":true,"gender":"Female",
"game_title":"Call of Gods","game_url":"http://www.kongregate.com/games/callofgods/call-of-gods"}}]}

Comments