Users.getInfo

From Facebook Developers Wiki

Jump to: navigation, search

Contents

[edit] Description

Returns a wide array of user-specific information for each user identifier passed, limited by the view of the current user. The current user is determined from the session_key parameter. The only storable values returned from this call are those under the affiliations element, the notes_count value, and the contents of the profile_update_time element.


[edit] Parameters

RequiredNameTypeDescription
required api_key string The application key associated with the calling application.
session_key string The session key of the logged in user.
call_id float The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function.
sig string An MD5 hash of the current request and your secret key, as described in the authentication guide.
v string This must be set to 1.0 to use this version of the API.
uids array List of user IDs. This is a comma-separated list of user IDs.
fields array List of desired fields in return. This is a comma-separated list of field strings.
optional format string Desired response format. Either XML (default) or JSON.
callback string Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known asJSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter.


[edit] Example Request

This is using the PHP library $user_details=$this->facebook->api_client->users_getInfo($uid, array('last_name','first_name')); $data['first_name']=$user_details[0]['first_name']; $data['last_name']=$user_details[0]['last_name'];


[edit] Example Return XML

<?xml version="1.0" encoding="UTF-8"?> <users_getInfo_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true"> <user> <uid>8055</uid> <about_me>This field perpetuates the glorification of the ego. Also, it has a character limit.</about_me> <activities>Here: facebook, etc. There: Glee Club, a capella, teaching.</activities> <affiliations list="true"> <affiliation> <nid>50453093</nid> <name>Facebook Developers</name> <type>work</type> <status/> <year/> </affiliation> </affiliations> <birthday>November 3</birthday> <books>The Brothers K, GEB, Ken Wilber, Zen and the Art, Fitzgerald, The Emporer's New Mind, The Wonderful Story of Henry Sugar</books> <current_location> <city>Palo Alto</city> <state>CA</state> <country>United States</country> <zip>94303</zip> </current_location> <education_history list="true"> <education_info> <name>Harvard</name> <year>2003</year> <concentrations list="true"> <concentration>Applied Mathematics</concentration> <concentration>Computer Science</concentration> </concentrations> </education_info> </education_history> <first_name>Dave</first_name> <hometown_location> <city>York</city> <state>PA</state> <country>United States</country> <zip>0</zip> </hometown_location> <hs_info> <hs1_name>Central York High School</hs1_name> <hs2_name/> <grad_year>1999</grad_year> <hs1_id>21846</hs1_id> <hs2_id>0</hs2_id> </hs_info> <is_app_user>1</is_app_user> <has_added_app>1</has_added_app> <interests>coffee, computers, the funny, architecture, code breaking,snowboarding, philosophy, soccer, talking to strangers</interests> <last_name>Fetterman</last_name> <locale>en_US</locale> <meeting_for list="true"> <seeking>Friendship</seeking> </meeting_for> <meeting_sex list="true"> <sex>female</sex> </meeting_sex> <movies>Tommy Boy, Billy Madison, Fight Club, Dirty Work, Meet the Parents, My Blue Heaven, Office Space </movies> <music>New Found Glory, Daft Punk, Weezer, The Crystal Method, Rage, the KLF, Green Day, Live, Coldplay, Panic at the Disco, Family Force 5</music> <name>Dave Fetterman</name> <notes_count>0</notes_count> <pic>http://photos-055.facebook.com/ip007/profile3/1271/65/s8055_39735.jpg</pic> <pic_big>http://photos-055.facebook.com/ip007/profile3/1271/65/n8055_39735.jpg</pic> <pic_small>http://photos-055.facebook.com/ip007/profile3/1271/65/t8055_39735.jpg</pic> <pic_square>http://photos-055.facebook.com/ip007/profile3/1271/65/q8055_39735.jpg</pic> <political>Moderate</political> <profile_update_time>1170414620</profile_update_time> <quotes/> <relationship_status>In a Relationship</relationship_status> <religion/> <sex>male</sex> <significant_other_id xsi:nil="true"/> <status> <message>Fast Company, November issue, page 84</message> <time>1193075616</time> </status> <timezone>-8</timezone> <tv>cf. Bob Trahan</tv> <wall_count>121</wall_count> <work_history list="true"> <work_info> <location> <city>Palo Alto</city> <state>CA</state> <country>United States</country> </location> <company_name>Facebook</company_name> <position>Software Engineer</position> <description>Tech Lead, Facebook Platform</description> <start_date>2006-01</start_date> <end_date/> </work_info> </work_history> </user> </users_getInfo_response>


[edit] Response

The user info elements returned are those friends visible to the Facebook Platform. If no visible users are found from the passed uids argument, the method returns an empty result element. Following is a list of arguments and the elements they return:

  • uid - The user ID corresponding to the user info returned. This is always returned, whether included in fields or not, and always as the first subelement.
  • about_me - text element corresponding to Facebook \'About Me\' profile section. May be blank.
  • activities - User-entered "Activities" profile field. No guaranteed formatting.
  • affiliations - list of network affiliations, as affiliation elements, each of which contain year, type, status, name, and nid child elements. If no affiliations are returned, this element will be blank. The user's primary network (key: nid) will be listed first.
    • type takes the following values:
      • college: college network
      • high school: high school network
      • work: work network
      • region: geographical network
    • year may be blank, depending on the network type.
    • name is the name of the network.
    • nid is a unique identifier for the network. The user-to-network relation may be stored.
    • status describes the user's graduate status if the network is a college network. Otherwise, it is blank.
  • birthday - User-entered "Birthday" profile field. No guaranteed formatting.
  • books - User-entered "Favorite Books" profile field. No guaranteed formatting.
  • current_location - User-entered "Current Location" profile fields. Contains four children: city, state, country, and zip.
    • city is user-entered, and may be blank.
    • state is a well-defind two-letter American state or Canadian province abbreviation, and may be blank.
    • country is well-defined, and may be blank.
    • zip is an integer, and is 0 if unspecified by the user.
  • education_history - list of school information, as education_info elements, each of which contain name, year, and concentration child elements. If no school information is returned, this element will be blank.
    • year is a four-digit year, and may be blank.
    • name is the name of the school, and is user-specified.
    • concentrations is a list of concentration elements, and may be an empty list.
  • first_name is generated from the user-entered "Name" profile field.
  • has_added_app - Bool (0 or 1) indicating whether the user has added the calling application to his facebook account.
  • hometown_location - User-entered "Hometown" profile fields. Contains four children: city, state, country, and zip.
    • city is user-entered, and may be blank
    • state is a well-defind two-letter American state or Canadian province abbreviation, and may be blank.
    • country is well-defined, and may be blank.
    • zip is an integer, and is 0 if unspecified by the user.
  • hs_info - User-entered high school information. Contains five children: hs1_name, hs2_name, grad_year, hs1_key, and hs2_key.
    • hs1_name is well-defined, and may be left blank
    • hs2_name is well-defined, and may be left blank, though may not have information if hs1_name is blank.
    • grad_year is a four-digit year, or may be blank
    • hs1_id is a unique ID representing that school, and is not zero if and only if hs1_name is not blank.
    • hs2_id is a unique ID representing that school, and is not zero if and only if hs2_name is not blank.
  • interests - User-entered "Interests" profile field. No guaranteed formatting.
  • is_app_user - Bool (0 or 1) indicating whether the user has used the calling application.
  • last_name is generated from the user-entered "Name" profile field.
  • locale is the current locale code in which the user has chosen to browse Facebook. The basic format is LL_CC, where LL is a two-letter language code, and CC is a two-letter country code. For instance, 'en_US' represents US English.
  • meeting_for - list of desired relationship types corresponding to the "Looking For" profile element. If no relationship types are specified, the meeting_for element is empty. Otherwise represented as a list of seeking child text elements, which may each contain one of the following strings: Friendship, A Relationship, Dating, Random Play, Whatever I can get.
  • meeting_sex - list of desired relationship genders corresponding to the "Interested In" profile element. If no relationship genders are specified, the meeting_sex element is empty. Otherwise represented as a list of sex child text elements, which may each contain one of the following strings: male, female .
  • movies - User-entered "Favorite Movies" profile field. No guaranteed formatting.
  • music - User-entered "Favorite Music" profile field. No guaranteed formatting.
  • name - User-entered "Name" profile field. May not be blank.
  • notes_count - Total number of notes written by the user.
  • pic - URL of user profile picture, with max width 100px and max height 300px. May be blank.
  • pic_big - URL of user profile picture, with max width 200px and max height 600px. May be blank.
  • pic_small - URL of user profile picture, with max width 50px and max height 150px. May be blank.
  • pic_square - URL of a square section of the user profile picture, with width 50px and height 50px. May be blank.
  • political - User-entered "Political View" profile field. It's a free-form text field.
  • profile_update_time - Time (in seconds since epoch) that the user's profile was last updated. If the user's profile was not updated recently, 0 is returned.
  • quotes - User-entered "Favorite Quotes" profile field. No guaranteed formatting.
  • relationship_status - User-entered "Relationship Status" profile field. Is either blank or one of the following strings: Single, In a Relationship, In an Open Relationship, Engaged, Married, It's Complicated.
  • religion - User-entered "Religious Views" profile field. No guaranteed formatting.
  • sex - User-entered "Sex" profile file. Either "male", "female", or left blank.
  • significant_other_id - the id of the person the user is in a relationship with. Only shown if both people in the relationship are users of the application making the request.
  • status - Contains a "message" child with user-entered status information, as well as a "time" child with the time (in seconds since epoch) at which the status message was set.
  • timezone - offset from GMT (e.g. California is -8).
  • tv - User-entered "Favorite TV Shows" profile field. No guaranteed formatting.
  • wall_count - Total number of posts to the user's wall.
  • work_history - list of work history information, as work_info elements, each of which contain location, company_name, position, description, start_date and end_date child elements. If no work history information is returned, this element is blank.
    • location is user-entered, and has a similar format to current_location and hometown_location above.
    • company_name is user-entered, and does not necessarily correspond to a Facebook work network.
    • description is user-entered, and may be blank.
    • position is user-entered, and may be blank.
    • start_date is of the form YYYY-MM, YYYY, or MM. It may be blank.
    • end_date is of the form YYYY-MM, YYYY, or MM. It may be blank.

Privacy note: For any user submitted to this method, the following user fields are visible to an application only if that user has signed up for that application:

  • meeting_for
  • meeting_sex
  • religion
  • significant_other_id

In addition, the visibility of all fields, with the exception of affiliations, first_name, last_name, name, and uid may be restricted by the user's Facebook privacy settings in relation to the calling user (the user associated with the current session).

If a field is not visible for either of the above reasons, then that field's corresponding element will be empty with a nil attribute set, in the following manner:

<significant_other_id xsi:nil="true"/>

Finally, a user profile query will not return any data if the user has turned off access to the Facebook Platform.


[edit] FQL Equivalent

This function is similar to doing the following FQL query, with the appropriate parameters filled in (for example, fields would be a list of fields described above):

SELECT uid, fields FROM user WHERE uid IN (uids)


[edit] Error Codes

CodeDescription
1 An unknown error occurred. Please resubmit the request.
2 The service is not available at this time.
4 The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed.
5 The request came from a remote address not allowed by this application.
100 One of the parameters specified was missing or invalid.
101 The API key submitted is not associated with any known application.
102 The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key.
103 The submitted call_id was not greater than the previous call_id for this session.
104 Incorrect signature.


[edit] Notes

To get higher-res images for the pic field, please see Profile archive album.

Retrieved from "http://wiki.developers.facebook.com/index.php/Users.getInfo"
Navigation