Upload Media

From KickApps Documentation

Contents 1 Overview 1.1 URI 1.2 Upload Form 1.3 Parameters 1.4 Post Parameters 1.5 JSON Payload 1.6 Restrictions and permissions 1.7 Supported File Types 1.8 Example Request 2 List of Kit Cloud Social API Calls

Overview

A multi-part HTTP POST request that uploads one or more new media files (audio, video, or photo) and descriptive content for the file, directly from the member. Examples in this section use the Java sample application, which uses a web form that is validated and posted to the server. You can also use the Upload media call for "Multiple Media Uploads".

URI

http://api.kickapps.com/rest/upload/{mediaType}/{as}

NOTE: Blog posts use a different URI: See the Add Blog Post section for details on adding blog posts.

Upload Form

The upload form (see UploadClient.jsp in the sample application) is hosted on your server. When using multipart form fields, the form's method should be set to POST and the form's enctype attribute should be set to multipart/form-data.

<form name="uploadForm" method="POST" enctype="multipart/form-data" action="processUpload.jsp">

Your form must have the exact name:value fields as shown below.

Name	Value
media	Required. The actual media file that will be uploaded.
ap	This image will appear in media summary lists and as the starting image for the media file.
name	Required. The name for this media. Max length 125 characters.
description	A text description of this media that will display to members. The text can be no longer than 5000 characters.
allowPublicTagging	true or false. Whether members can tag this media.
allowPublicCommenting	true or false. Default is true. By default, form is set to true. Whether members can comment on this media.
tags	One or more comma-separated keyword tags. Enclose multi-word tags inside quotations ("tag tag",tag). You can also add tags to an existing media item using the separate Add Tags call. Each mediaId can have a maximum of 512 characters of associated tags, including the commas that separate each tag. Each tag must not be longer than 20 characters, not including the commas that separate each tag. Use URL-encoded space characters (%20) to create spaces between words. Tags cannot include special characters, only letters, numbers, and spaces.
adminTags	One or more comma-separated tags. You must be logged in as an administrator in order to add admin tags. Enclose multi-word tags inside quotations ("tag tag",tag). Each mediaId can have a maximum of 512 characters of associated tags, including the commas that separate each tag. Each tag must not be longer than 20 characters, not including the commas that separate each tag. Use URL-encoded space characters (%20) to create spaces between words. Tags cannot include special characters, only letters, numbers, and spaces.
category	Optional. Up to three levels of categories that members can use to find this media, written in the following format level1name/level2name/level3name. Level names should be preexisting categories for this site. An error will be returned if you try to add a category that does not already exist.
country	The member's country. The values in your upload form must exactly match those used by KIT Cloud Social. If country is 1 for the United States of America, 2 for Canada, or 15 for Australia, the value for the Zip or Postal Code field will also be validated.
state	The abbreviation for the member's state. The value selected in the upload form will correspond to those shown on this page: Geographic Values for Media Uploads.
stateOrProvince	The abbreviation for the member's province. The value selected in the upload form will correspond to those shown on this page: Geographic Values for Media Uploads.
AusState	The abbreviation for the member's state. The value selected in the upload form will correspond to those shown on this page: Geographic Values for Media Uploads.
otherStateOrProvince	The abbreviation for the member's state or province if country is not 1 for the United States of America, 2 for Canada, or 15 for Australia. Zip and postal codes are not validated for these values.
city	The member's city. The max character length for this field is 128 characters.
zipcode	The member's zip or postal code. The max character length for this field is 32 characters. If country is 1 for the United States of America, 2 for Canada, or 15 for Australia, the value for the Zip or Postal Code field will also be validated.
updatedAt	Optional. The date on which the media should be marked as modified. If its not passed the the time this call is made will be used. Format: mm/dd/yyyy hh:mm
createdAt	Optional. The date on which the media should be marked as created. If its not passed the the time this call is made will be used. Format: mm/dd/yyyy hh:mm

Parameters

Your upload will include the following parameters:

• mediaType. The media type. audio, photo, or video. KIT Cloud Social's sample applications use mediaType to check for the Flash player to use. When your write your post request, this value would appear like the following.

filePost = new PostMethod(http://api.kickapps.com/rest/upload/{mediaType}/{as});

• af or as. The affiliate site that the media will be associated with. Each affiliate site has a unique as.

Post Parameters

• t. String. Required. Your access permissions.
• callback. String. Optional. The name of your JavaScript callback function.
• clientIP. String. Optional. Use the clientIP parameter to pass the IP address of the user making the call. If the IP has been blocked by the webmaster under the Affiliate Center -> Manage Members section, an error message will be returned starting with "status":"-1","error":"This IP address has been banned".
• isProfileImage. Optional. Sets the photo as the profile photo. Default is F for false, to enable set to T for true.
• status. Optional. active or pending. To bypass the moderation settings and post media as active i.e. available on site immediately set the status to be "active. To add the media as pending for webmaster approval set status to be "pending". If no value is passed the media will be given a status based on the default moderation settings. This param can only be accessed by the webmaster, admin or the editor.
• isAddToMediaSetAllowed. True or False. True if other community members can add this media to their sets. False if other community members are not permitted to add this media to their sets.

JSON Payload

If you do not include a category with the new media, you will also receive an error message of “category invalid or empty.” You can ignore this message – categories are not required.

On success, a payload that begins with "status":"1","error":"" and the following:

• mediaId. The media Id of the media that was uploaded.

Restrictions and permissions

The media upload call is also subject to these restrictions:

• Live audio/video captures are not supported by the REST API.
• The media file being uploaded must be "14 MB or smaller for photos" all other media types must be 100 MB or smaller.

Supported File Types

Type	Supported File Types
audio	MP3
photo	JPEG, PNG, and GIF
video	.WMV, .ASF, .AVI, .MOV, .3GP, .MPG, .MPEG, .FLV and.MP4.

Example Request

You can also use the Upload Media call to upload multiple media files from the same directory by using a script such as the following:

PHP Example

echo "Uploading $file\n
"; flush(); $postData = array();

$postData[ 'media' ] = '@' . $file; $postData[ 'name' ] = 'photo'; $postData[ 'allowPublicTagging' ] = 'true'; $postData[ 'allowPublicCommenting' ] = 'true'; $postData[ 'tags' ] = 'foo'; $postData[ 't' ] = $token; $postData[ 'submit' ] = 'UPLOAD'; $postData[ 'category' ] = ;

$ch = curl_init(); $url = BASE_URI . "upload/photo/" . $as ; echo $url; curl_setopt($ch, CURLOPT_URL, $url ); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_POST, 1 );

curl_setopt($ch, CURLOPT_POSTFIELDS, $postData ); $response = curl_exec( $ch );

List of Kit Cloud Social API Calls

API Change Log Create Token Call Social Networking Retrieve Member Profile Add Or Remove Member As Friend Get A Member's Friends, Fans, and "Fan Of" Retrieve User by Facebook Id KickConnect Assign Member Profile Photo Remove Member Profile Photo Member Profile Edit/Update SSO Method Member Register SSO Method Combined Member Sign On and Register SSO Method Member Change Username SSO Method Member Change Email SSO Method OpenAuth Create Message Board Media Sharing Upload Media Retrieve Media Meta Data Edit Media Meta Data Delete Member Media Retrieve Play Page Retrieve Member Media Retrieve Member's Favorite Media Retrieve Related Media Member Favorite Media Check Email Media Add Or Remove Media Flag Add To Or Remove From Favorites Geographic Values for Media Uploads Get Video Thumbnails Set Video Thumbnail Blogging Add Blog Post Edit Blog Post Comments and Rating Add External Media Retrieve External Media Edit External Media Add Group Comment Add Media Comment Add Profile Comment Retrieve Comments Search Comments Edit Comment Edit Group Comment Delete Comment Delete Group Comment Flag Comment Flag Group Comment Rate Media Retrieve Media Ratings Retrieve Media Rated By Member Retrieve Likes By User ID Search Search Media Sets Add Media Set Edit Set Retrieve Set Delete Set Add Media to Set Remove Media from Set Groups Add Group Retrieve Group Page Edit Group Request A Group Add/Remove Media To Group Add/Remove Member To Group Retrieve Member Groups Upload Group Photo Remove Group Photo Polls Creating Polls Using the Tag API’s

Badges Add Badge Edit Badge List Badges Add Action List Actions Add Badge Requirement Edit Badge Requirement List Badge Requirements Add User Action Retrieve User's Badges Retrieve User's Badge Status Retrieve Super Fans Get Super Fan Ranking Set Super Fan Badge Criteria Contests Add Contest Edit Contest View Contest Retrieve All Contests Add Contest Entry Edit Contest Entry Remove Contest Entry View Contest Entry Retrieve Contest Entries Select Contest Winner Flag Contest Entry Add to Member Offset Retrieve Member Points Set Member Custom Level Set Member Offset Categories and Tags Add Tags To Media, Members and Groups Remove Tags From Media, Members and Groups Add Admin Tags To Media, Members and Groups Remove Admin Tags From Media, Members and Groups Retrieve Admin Tags Retrieve Tag Count Add Category Edit Category Retrieve Category Delete Category Add Custom Meta Data Remove Custom Meta Data Retrieve Custom Meta Data Member and Media Management Approve Member Reject Member Approve Member Media Reject Member Media Delete Member Media Retrieve Pending Media Retrieve Active Member Count Retrieve Site Settings CRM Connectors SugarCRM Connector Salesforce Connector CRM Connectors (COMING SOON!!) IBM Websphere Microsoft Dynamic CRM NetSuite Oracle CRM On Demand Oracle E-Business Suite CRM PeopleSoft Enterprise CRM Oracle Siebel CRM SAP CRM Sugar Professional Maximizer CRM Pegasystems Customer Process Manager

Note: Occasionally (and without advanced warning) we modify our API calls by adding new parameters in the response payload. Please keep this in mind when designing your strategy for parsing our responses.