REST API :: Return Values
Following is a complete list of fields returned face.com's API responses:
Tag Response Fields
Methods: faces.detect, faces.recognize, faces.group, tags.get, facebook.get
| Field | Type | Description |
|---|---|---|
| photos | array | List of all the photo objects that were included in the request, one photo per URL specified |
| url | string | Photo url as specified in the request |
| pid | string | Photo id on the face.com platform, can be used as reference instead of URL for follow-up calls to methods that support it |
| width | integer | Photo width in pixels |
| height | integer | Photo height in pixels |
| tags | array | List of zero or more face tag objects found in the photo |
| groups | array | List of one or more groups of faces found in photos, when using faces.group. Each object in this array contains: gid: The group's ID uid: A matching UID for the group. Only works if the call provides a list of UIDs, and a UID is matched with this group tids: A list of one or more Tag Ids (see tid below).Note: If the gid=null and the uid=null, this means this is the ungrouped group. Those are all the faces that had no matching face, or faces that cannot be group at the moment (such as profile posed faces). |
| tid | string | Tag id on the face.com platform. Tag IDs are temporary until used in tags.save calls to associate the tag with a specific user ID, at which point they become persistent. |
| recognizable | boolean | Not all tags can be used for recognition or training (For example, profile posed faces). This fields is True for tags that can be recognized or can be used for training set. False otherwise. For tags that were saved before this field was added to the API, value is null, which means it can be either recognizable or not. |
| threshold | integer | (faces.recognize only) The recommended confidence threshold from 0-100 to use when deciding which recognition results to display. The threshold changes based on the quality of faces found, as well as the size of the uids list specified when calling faces.recognize. |
| uids | array | (faces.recognize only) List of possible matches for the face tag. Each entry in this list has 2 fields: uid: a user id match for the face tag. Only uids that were specified during the faces.recognize call (either explicitly or through a list) will be returned. confidence: score from 0-100 (%). Refer to the threshold field for a recommendation of which confidence scores are high/low for this call. When tags are saved, the confidence score is always 100. |
| label | string | Optional text label describing the tag. must have been previously specified through a tags.add or tags.save call. |
| confirmed | boolean | Specifies whether a tag has been confirmed or is in a temporary state. Tags are confirmed through calls to tags.save, tags.add, and with facebook tags - via facebook's user interface. Unconfirmed tags are also referred to as temporary, which means that they are not persisted anywhere.All confirmed tags have the confidence score of 100. |
| manual | boolean | False by default, on true if the tag was added through the tags.add call which supports manual addition of otherwise undetected faces. |
| (tag) width | float | Face tag width as 0-100% of photo width |
| (tag) height | float | Face tag height as 0-100% of photo height |
| center | array | x & y coordinates of tag face's center point, as 0-100% of photo width and height |
| eye_left | array | x & y coordinates of left eye, as 0-100% of photo width and height |
| eye_right | array | x & y coordinates of right eye, as 0-100% of photo width and height |
| mouth_left | array | x & y coordinates of left edge of mouth, as 0-100% of photo width and height |
| mouth_center | array | x & y coordinates of center of mouth, as 0-100% of photo width and height |
| mouth_right | array | x & y coordinates of right edge of mouth, as 0-100% of photo width and height |
| nose | array | x & y coordinates of nose tip, as 0-100% of photo width and height |
| yaw | float | yaw (facing sideways) angle value as -90 to 90 |
| pitch | float | pitch (up or down) angle value as -90 to 90 |
| roll | float | roll (face rotation) angle value as -90 to 90 |
| attributes | array | list of detected facial attributes (currently gender, glasses, and smiling) - Each attribute object consist of two fields: confidence and value. Value is a string. Confidence - int (precent) |
| gender | object | male/female value and confidence |
| glasses | object | true/false value and confidence, true when glasses are detected |
| smiling | object | true/false value and confidence, true when a person is smiling in a photo |
| mood | object | happy/sad/angry/surprised/neutral value and confidence, based on the expression of the person in the the photo. |
| lips | object | sealed/parted/kissing value and confidence, describing the state of the person's lips |
| face | object | value is always set to true. confidence of this tag being a face. Confidence lower than 50% have high probability being false-positives |
Response Status
methods: all
| Field | Type | Description |
|---|---|---|
| status | string | 'success', 'failure', or 'partial'. Partial is used when a request has multiple photos in the response, and has one or more failures mixed with successful responses (e.g. wrong URLs in for some of the photos specified). |
| error_code | integer | error code, specified only when an error occurs |
| error_message | string | error message, specified only when an error occurs |
Usage Response
methods: all rate limited methods, account.limits
| Field | Type | Description |
|---|---|---|
| used | integer | amount of photos that were processed since last rate-limit reset time (1 hour) |
| remaining | integer | amount of photos remaining in current time window |
| limit | integer | the total photos limit permitted in the current 1-hour window |
| reset_time | integer | GMT unix-timestamp of next limit reset time |
| reset_time_text | string | GMT unix-timestamp of next limit reset time (in text) |
Error Codes
methods: all
| error_code | error_message |
|---|---|
| 20 | IMG_DECODE_ERROR |
| 21 | IMG_RESIZE_ERROR |
| 30 | DOWNLOAD_ERROR |
| 31 | DOWNLOAD_ERROR_FILE_NOT_FOUND |
| 32 | DOWNLOAD_ERROR_SERVER_TIMEOUT |
| 33 | DOWNLOAD_ERROR_FILE_TOO_LARGE |
| 34 | DOWNLOAD_ERROR_MALFORMED_URL |
| 35 | DOWNLOAD_ERROR_UNKNOWN_HOST |
| 36 | DOWNLOAD_ERROR_CONNECTION_REFUSED |
| 104 | INTERNAL_ERROR |
| 105 | SERVICE_TEMPORARILY_UNAVAILABLE |
| 107 | UNKNOWN_ERROR |
| 201 | API_KEY_DOES_NOT_EXIST |
| 202 | API_KEY_USAGE_PASSED_QUOTA |
| 203 | API_KEY_CONCURRENT_USAGE_PASSED_QUOTA |
| 204 | API_KEY_NOT_AUTHENTICATED |
| 205 | API_PASSWORD_NOT_CORRECT |
| 206 | MAX_NUMBERS_OF_UIDS_TRAINED_IN_NAMESPACE_EXCEEDED |
| 207 | TOO_MANY_ERRORS |
| 301 | TAG_NOT_FOUND |
| 302 | FACEBOOK_EXCEPTION |
| 303 | FILTER_SYNTAX_ERROR |
| 304 | AUTHORIZATION_ERROR |
| 305 | TWITTER_EXCEPTION |
| 306 | TAG_ALREADY_EXIST |
| 307 | ACTION_NOT_PERMITTED |
| 401 | UNKNWOWN_REST_METHOD |
| 402 | MISSING_ARGUMENTS |
| 403 | MISSING_USER_NAMESPACE |
| 404 | UNAUTHORIZED_USER_NAMESPACE |
| 405 | UNAUTHORIZED_UID |
| 406 | INVALID_ARGUMENTS_VALUE |
| 407 | ARGUMENT_LIST_TOO_LONG |
| 408 | UNAUTHORIZED_CALLBACK_URL_DOMAIN |
| 409 | UID_TOO_LONG |
| 410 | SYNCHRONOUS_REQUEST_TOO_BIG |