REST API :: tags.get
Returns saved tags in one or more photos, or for the specified User ID(s). 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.
Photos can also be uploaded directly in the API request. A requests that uploads a photo must be formed as a MIME multi-part message sent using POST data. Each argument, including the raw image data, should be specified as a separate chunk of form data. (See example in detect)
usage notes:
- Either urls, uids, pids, or uploaded photo must be specified
- This method has no usage limits
url:
http://api.face.com/tags/get.format
parameters:
| Required | Name | Description |
|---|---|---|
| Required | api_key | your face.com API Key |
| api_secret | your face.com API Secret | |
| Optional | [no name] | The raw image data for the photo (when instead of url, an image is uploaded) |
| uids | a comma separated list of user IDs to fetch | |
| urls | a comma separated list of JPG photos to fetch tags from | |
| pids | photo IDs to fetch tags from (as returned by faces.detect and faces.recognize) | |
| order | Specify 'recent' for latest tags, and 'random' to randomly select tags. Default: 'recent' | |
| limit | set maximum limit for number of tags to return. Default: 5 | |
| together | when providing multiple uids, return only photos where ALL uids appear together in the photo(s). Default: false | |
| filter | provide 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 yaw Where: uid - user id Separators: | |
| namespace | a default user namespace to be used for all users specified in the short-hand syntax (just the user ID, without the '@namespace') | |
| format | ‘json’ (default) or ‘xml’ | |
| callback | javascript method to wrap a json-formatted response (for JSONP support, ignored if format=xml) | |
| user_auth | signed-in facebook or twitter user credentials. Required only when specifying UIDsin these namespaces. Use name:value pairs, separated by comma:
|
examples:
Get recent tag saved for 571756321@facebook.com:
http://api.face.com/tags/get.json?api_key=4b4b4c6d54c37&api_secret= &uids=571756321@facebook.com&order=recent&limit=1
Get all tags saved for a photo url:
http://api.face.com/tags/get.json?api_key=4b4b4c6d54c37&api_secret=&urls=http://farm5.static.flickr.com/4064/4276720981_d4872b1649.jpg
Get all tags in photos where both 571756321@facebook.com and 4@facebook.com appear together:
http://api.face.com/tags/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: 200,
limit: 200,
reset_time_text: "Sat, 06 Mar 2010 15:09:39 +0000",
reset_time: "1267888179"
}
}