Photos.addTag
From Facebook Developers Wiki
Contents |
[edit] Description
Adds a tag with the given information to a photo. See photo uploads for a description of the upload workflow.
For regular applications, tags can only be added to pending photos owned by the specified user or the current session user – once a photo has been approved or rejected, it can no longer be tagged with this method. Applications with the photo_upload extended permission can add tags to any photo owned by the user. There is a limit of 20 tags per pending photo.
For Web applications, you must pass either the ID of the user on whose behalf you're making this call or the session key for that user, but not both. If you don't specify a user with the owner_uid parameter, then that user whose session it is will be the target of the call.
However, if your application is a desktop application, you must pass a valid session key for security reasons. Do not pass a uid parameter.
[edit] Parameters
| Required | Name | Type | Description | |
| 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 authentication guide. | ||
| v | string | This must be set to 1.0 to use this version of the API. | ||
| pid | int | The ID of the photo to be tagged. | ||
| tag_uid | int | The ID of the user being tagged. You must specify either the tag_uid or the tag_text parameter, but not both. They have no defaults and this parameter is ignored if tag_text is specified. | ||
| tag_text | string | Some text identifying the person being tagged. You must specify either the tag_uid or the tag_text parameter, but not both. They have no defaults and this parameter is ignored if tag_uid is specified. | ||
| x | float | The horizontal position of the tag, as a percentage from 0 to 100, from the left of the photo. | ||
| y | float | The vertical position of the tag, as a percentage from 0 to 100, from the top of the photo. | ||
| optional | session_key | string | The session key of the user who is being tagged in a photo. Note: A session key is always required for desktop applications. It is required for Web applications only when the owner_uid is not specified. | |
| format | string | Desired response format. Either XML (default) or JSON. | ||
| 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. | ||
| tags | string | A JSON-serialized array representing a list of tags to be added to the photo. If the tags parameter is specified, the x, y, tag_uid, and tag_text parameters are ignored. Each tag in the list must specify: "x", "y", and either the user id "tag_uid" or free-form "tag_text" identifying the person being tagged. An example of this is the string
[{"x":"30.0","y":"30.0","tag_uid":1234567890}, {"x":"70.0","y":"70.0","tag_text":"some person"}] | ||
| owner_uid | int | The user ID of the user whose photo you are tagging. If this parameter is not specified, then it defaults to the session user. Note: This parameter applies only to Web applications and is required by them only if the session_key is not specified. Facebook ignores this parameter if it is passed by a desktop application. |
[edit] Example Return XML
| <?xml version="1.0" encoding="UTF-8"?> <photos_addTag_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"> 1 </photos_addTag_response> |
[edit] Error Codes
| Code | Description | |
| 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. | |
| 110 | Invalid user ID. | |
| 121 | Invalid photo ID. | |
| 200 | The application does not have permission to operate on the passed in uid parameter. | |
| 260 | Modifying existing photos requires the extended permission photo_upload. | |
| 322 | Invalid photo tag subject. | |
| 323 | Cannot tag photo already visible on Facebook. | |
| 326 | Too many photo tags pending. |
[edit] Notes
- This function does not require a
session_key, unless it is being called by a desktop application.
