Documentation :: REST API

REST Interface

The face.com API uses REST-like interface. This means that all calls to the API are made over the Internet, using HTTP GET and POST requests to the face.com API server (http://api.face.com). Any programming language that can be used to communicate over HTTP can be used for client-side implementations, and we have some common libraries to get you started.

Responses are returned in JSON or XML formats. We also support JSONP callbacks for cross-site mash-ups (use the callback parameter in your calls to specify which client-side callback method to call).

Some  XML reponse conventions:

• Arrays will be marked with list="true" attribute. We use this to hind the parser, that a certain element list, regardless of its length should be used as an array, when converting xml to object. This means that even for list with only one item, the object's property should be an array containing one element. In JSON, me make sure to use array notation '[' so this is trivial for the parser.
• Null values of all fields are represented by empty nodes. i.e: <eye_left_x></eye_left_x> (in json, again its trivial. i.e: eye_left_x: null)

Note: When one of the parameters passed to the REST call is long (for example, many comma separated urls), the GET method might not work well, due to parameters length limitation on query string. The result would be "MISSING_ARGUMENTS" error (error_code: 402).  In those cases, calls to the API should be made using POST method.

API Methods

Recognition engine methods

faces.detect
Detect faces in photos

faces.recognize
Recognize faces in photos

faces.train
Trains the index with one or more faces

faces.status
Returns the current index status

Methods for managing face tags

tags.get
Returns saves tags for photos and users

tags.add
Adds a manual face tag

tags.save
Saves an automatically-detected face tag

tags.remove
Removes a saved tag

Account management methods

account.limits
Returns current account's rate and namespace limits

account.users
Returns all registered user IDs for an account's private namespace

Return Values

For a complete description of return values, head over to the Return Values section