REST API :: facebook.get

Returns facebook tags for one or more specified User IDs. This method also accepts multiple filters for finding tags corresponding to a more specific criteria such as front-facing, recent, or where two or more users appear together in same photos.

Using this method assures that the facebook tags you're receiving have a detectable face in them, making them more suitable for use in various applications. This method works by running faces.detect on photos with facebook tags of the requested UIDs, and then estimates which of the faces found is the actual UID you requested. This also means that we will be analyzing about 3 photos per returned tag (the rest will be filtered out), setting the rate costs at x3 than a normal detect or recognize call.

rate limiting (info):

This API is rate limited. Each returned tag adds 3 counts to your usage.

usage notes:

  • Total rate-limit costs for this method are calculated as 3 times the number of tags returned
  • Using limits is recommended since every call to this method also spends time in accessing the facebook API, and also has a higher rate cost

Try it now on the API Sandbox

url:

http://api.face.com/facebook/get.format

parameters:

RequiredNameDescription
Requiredapi_keyyour face.com API Key
api_secretyour face.com API Secret
uidsa comma separated list of user IDs to fetch
user_authsigned-in facebook user credentials. Use name:value pairs, separated by comma:

  • fb_user:[facebook user id]
  • [Deprecated] fb_session:[facebook session id]
  • fb_oauth_token [facebook OAuth 2.0 access token]
OptionalorderSpecify 'recent' for latest tags, and 'random' to randomly select tags. Default: 'recent'
limitset maximum limit for number of tags to return. Default: 5
togetherwhen providing multiple uids, return only photos where ALL uids appear together in the photo(s). Default: false
filterprovide advanced facial geometry and attribute filtering:examples:
glasses:false,smiling:false - only return tags of faces without glasses and non smiling
gender:female,yaw:left,roll:-20~20 - only returns tags of females looking left with a roll tolerance of 20 degrees to either side
smiling:true|uid:1234@facebook.com,yaw:left- only return smiling faces, but for uid 1234@facebook.com also make sure a left yawWhere:uid - user id
gender - male/female
glasses - true/false
smiling - true/false
yaw - left/right/center OR range (x~y) of angle
roll - left/right/center OR range (x~y) of angle
pitch - up/down/center OR range (x~y) of angle
size - range (x~y) of size in pixels

Separators:
:  separates key:value pair
,  separates filter component
|  separates filter set for new person/group
~ range (i.e. 40~100)

format‘json’ (default) or ‘xml’
callbackjavascript method to wrap a json-formatted response (for JSONP support, ignored if format=xml)

examples:

Get recent tag saved for 571756321@facebook.com:
http://api.face.com/facebook/get.json?api_key=4b4b4c6d54c37&api_secret= &uids=571756321@facebook.com&order=recent&limit=1

Get all tags in photos where both 571756321@facebook.com and 4@facebook.com appear together:

http://api.face.com/facebook/get.json?api_key=4b4b4c6d54c37&api_secret= &uids=4,571756321&order=recent&namespace=facebook.com&together=true

response sample (json, truncated):

View complete list of response fields

{
    photos: [
        {
            url: "http://photos-d.ak.fbcdn.net/hphotos-ak-snc3/hs467.snc3/25630_335603057366_542437366_3439411_3436837_n.jpg",
            pid: "2329750747101821747_542437366",
            width: 604,
            height: 404,
            tags: [
                {
                    id: "2329750747101821747_542437366_39.90_37.38_0",
                    threshold: null,
                    uids: [
                        {
                            uid: "571756321@facebook.com",
                            confidence: 100
                        }
                    ],
                    label: "Gil Hirsch",
                    confirmed: true,
                    manual: false,
                    width: 8.61,
                    height: 12.87,
                    center: {
                        x: 39.9,
                        y: 37.38
                    },
                    eye_left: {
                        x: 38.51,
                        y: 35.39
                    },
                    eye_right: {
                        x: 41.77,
                        y: 36.13
                    },
                    mouth_left: {
                        x: 38.1,
                        y: 40.03
                    },
                    mouth_center: {
                        x: 39.72,
                        y: 41.05
                    },
                    mouth_right: {
                        x: 41.17,
                        y: 40.64
                    },
                    nose: {
                        x: 40.3,
                        y: 39.04
                    },
                    yaw: 23.66,
                    roll: 8.63,
                    pitch: -8.9,
                    attributes: {
                        gender: {
                            value: "male",
                            confidence: 95
                        },
                        glasses: {
                            value: "false",
                            confidence: 7
                        },
                        smiling: {
                            value: "true",
                            confidence: 86
                        }
                    }
                }
            ]
        }
    ],
    status: "success",
    usage: {
        remaining: 197,
        limit: 200,
        reset_time_text: "Sat, 06 Mar 2010 15:09:39 +0000",
        reset_time: "1267888179"
    }
}