Users.getInfo

From Facebook Developer Wiki

Jump to: navigation, search

Contents

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, the proxied_email address, and the contents of the profile_update_time element.

Use this call to get user data that you intend to display to other users (of your application, for example). If you need some basic information about a user for analytics purposes, call users.getStandardInfo instead.

This call no longer requires a session key. However, if you call this method without a session key, you can only get the following information:

  • uid
  • first_name
  • last_name
  • name
  • locale
  • affiliations (regional type only)
  • pic_square
  • profile_url

You can call this method as soon as a user interacts with your application, before she has authorized your application to access her information. If you do so, you can get the same information as you can without a session (see above).

User Privacy and Visible Data

Important: Depending upon the user's privacy settings (including whether the user has decided to opt out of Platform completely), you may not see certain user data. For any user submitted to this method, the following user fields are visible to an application only if that user has authorized 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 Facebook Platform.

Parameters

RequiredNameTypeDescription
required api_key string The application key associated with the calling application.
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 How Facebook Authenticates Your Application.
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 session_key string The session key of the logged in user.
format string The desired response format, which can be either XML or JSON. (Default value is XML.)
callback string Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter.

Example Requests

This is using the PHP library

$user_details = $facebook->api_client->users_getInfo($uid, 'last_name, first_name'); $data['first_name'] = $user_details[0]['first_name']; $data['last_name'] = $user_details[0]['last_name'];

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-defined name of the state, 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.
    • degree is the name of the degree, and may be blank.
  • email_hashes is an array containing a set of confirmed email hashes for the user. Emails are registered via the connect.registerUsers API call and are only confirmed when the user adds your application. The format of each email hash is the crc32 and md5 hashes of the email address combined with an underscore (_).
  • first_name is generated from the user-entered "Name" profile field.
  • has_added_app - [Deprecated] Bool (0 or 1) indicating whether the user has authorized the application. This value is now equivalent to is_app_user.
  • hometown_location - User-entered "Hometown" profile fields. Contains three children: city, state, and country.
    • city is user-entered, and may be blank
    • state is a well-defined name of the state, and may be blank.
    • country is well-defined, and may be blank.
  • 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 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. Country codes are taken from the ISO 3166 alpha 2 code list. 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_with_logo - URL of user profile picture with a Facebook logo overlaid, 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_big_with_logo - URL of user profile picture with a Facebook logo overlaid, 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_small_with_logo - URL of user profile picture with a Facebook logo overlaid, 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.
  • pic_square_with_logo - URL of a square section of the user profile picture with a Facebook logo overlaid, with width 50px and height 50px. May be blank.
  • political - User-entered "Political View" profile field. It's a free-form text field.
  • profile_blurb - A free-form text field under a user's profile picture.
  • profile_update_time - Time (in seconds since epoch) that the user's profile was last updated. If the user's profile was not updated within the past 3 days, 0 is returned.
  • profile_url - URL of the Facebook profile of the user.
  • proxied_email - A proxied wrapper alternative for contacting the user through email, instead of directly calling notifications.sendEmail.
  • 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. Note that this does not include items with attachments, i.e. wall photos, wall videos, posted links, etc. Only items that show up on http://www.facebook.com/wall.php are included in this count.
  • 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.

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>California</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> <family list="true"> <family_elt list="true"> <family_elt_elt>mother</family_elt_elt> <family_elt_elt>1394244902</family_elt_elt> </family_elt> <family_elt list="true"> <family_elt_elt>sister</family_elt_elt> <family_elt_elt>48703107</family_elt_elt> </family_elt> <family_elt list="true"> <family_elt_elt>brother</family_elt_elt> <family_elt_elt>1078767258</family_elt_elt> </family_elt> <family_elt list="true"> <family_elt_elt>brother</family_elt_elt> <family_elt_elt>John Doe</family_elt_elt> <family_elt_elt/> </family_elt> </family> <first_name>Dave</first_name> <hometown_location> <city>York</city> <state>Pennsylvania</state> <country>United States</country> </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_big> <pic_small>http://photos-055.facebook.com/ip007/profile3/1271/65/t8055_39735.jpg</pic_small> <pic_square>http://photos-055.facebook.com/ip007/profile3/1271/65/q8055_39735.jpg</pic_square> <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>


FQL Equivalent

FQL queries take the form: SELECT <fields> FROM <table> WHERE <conditions>

This function is similar to doing the following FQL query, with the appropriate parameters specified (note you can SELECT any fields from the User (FQL) table):

SELECT uid, current_location FROM user WHERE <uid> IN (uid)

Error Codes

CodeDescription
1 An unknown error occurred. Please resubmit the request.
2 The service is not available at this time.
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.
601 Error while parsing FQL statement.

Notes

  • Note that the uids field is not optional; you must specify this even if you have a session_key specified.
Retrieved from "http://wiki.developers.facebook.com/index.php/Users.getInfo"
reference