COVERITLIVE API - PIN/LIST (V. 2.0)

The Request

This method provides a list of pin items for a particular event. Both published and unpublished pin items can be retrieved.

URL:
https://api.coveritlive.com/remote/2/pin/list
Response Format:
JSON
HTTP Method(s):
GET
API Rate Limited:
false
In addition to the parameters listed in the Request Parameters section, the pin/list method also includes the following parameters:

Parameter Description Required
event_code The event code for the event for which pin data is being retreived. Each CiL event that is created is assigned a unique event code that identifies it in the database - The event owner can find this value after creating a new event, by selecting the "altcast_code" which is found in their Viewer Window embed code (e.g. the event code is "46e6cd22b5" in "altcast_code=46e6cd22b5"). This value is also returned by the event/list API method. yes
status A pipe (|) delimited list of pin item types of retrieve. Possible values include

published - pin items that are visible in viewer windows.

unpublished - pin items that have been created but are not currently visible in viewer windows.

Example parameter values: "published", "unpublished", "published|unpublished"
yes

The Response

The pin item listing data is returned in the data field of a general response. This field will consist of an array of pin item objects. These objects are enumerated below.

host_comment objects have the following fields:


Field Name Field Value(s) Explanation
type host_comment Describes the type of this object.
pin_id {string} ID of this pin item.
timestamp {int} Date and time the pin item was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For host_comment items this field is set to "y", indicating that they can be edited.
author_name {string} Display name of the author/initiator of the item. Empty if not applicable.
author_avatar {string} URL of thumbnail image associated with author_name. Empty if none provided. (NOTE: Image size is not guaranteed and may vary depending on image source and type. It is recommended that consumers of the Event Data feed adjust image size appropriately for the destination environment.)
comment {string} Comment text

guest_comment objects have the following fields:


Field Name Field Value(s) Explanation
type guest_comment Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time the pin item was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For guest_comment items this field is set to "y", indicating that they can be edited.
author_name {string} Display name of the author/initiator of the item. Empty if not applicable.
source {string} The source of the comment, currently this value is either empty or contains the string: api. If Reader Comment API was enabled on the event and your application had submitted the comment through the API the source value returned would indicate this.
comment {string} Comment text

audio objects have the following fields:


Field Name Field Value(s) Explanation
type audio Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time object was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable n Indicates whether the pin item can be edited through the API. For audio items this field is set to "n", indicating that they can NOT be edited.
uri {string} URI of audio file.
embed {string} Flash embed code for playing audio.
name {string} User provided name of file or filename on disk if not provided

image objects have the following fields:


Field Name Field Value(s) Explanation
type image Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time object was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For image items this field is set to "y", indicating that they can be edited.
embed {string} URI within HTML IMG tag optionally with link surrounding it.
uri {string} URI of full sized image file
uri_height {int} Pixel display height for the image file.
uri_width {int} Pixel display width for the image file.
uri_thumb {string} URI for optional thumbnail image file.
caption {string} User provided image caption data. Empty if no caption provided.
name {string} User provided name of file or filename on disk if not provided.

video objects have the following fields:


Field Name Field Value(s) Explanation
type video Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time object was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable n Indicates whether the pin item can be edited through the API. For video items this field is set to "n", indicating that they can NOT be edited.
uri {string} HTTP page of video file if file is hosted (Ustream, LiveStream, Qik.com), empty otherwise.
embed {string} Embedding HTML code for display of video - commonly YouTube.
name {string} User provided name of file or filename on disk if not provided.

tweet objects have the following fields:


Field Name Field Value(s) Explanation
type tweet Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time the pin item was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For tweet items this field is set to "n", indicating that they can NOT be edited.
author_name {string} Display name of the tweet author.
author_avatar {string} URI of the tweet author's avatar.
comment {string} Tweet text with entities replaced.
tweet_data {object} An object containing additional tweet data. See below

tweet_data objects have the following fields:


Field Name Field Value(s) Explanation
id {string} The string representation of the unique identifier for this Tweet. Equivalent to the id_str field in Tweet objects in the Twitter API.
name {string} The display name of the tweet author.
username {string} The username of the tweet author.
created_at {string} UTC time when the tweet was created. Equivalent to the created_at field in Tweet objects in the Twitter API

instagram objects have the following fields:


Field Name Field Value(s) Explanation
type image Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time object was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For instagram items this field is set to "n", indicating that they can NOT be edited.
author_name {string} The Instagram username of the user who created the original image.
link {uri} Link to the original image page in Instagram.
images {object} A JSON object containing the image details, including width, height and url.
comment {string} The tags/caption attached to the Instagram image.

wikipedia objects have the following fields:


Field Name Field Value(s) Explanation
type image Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time object was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For wikipedia items this field is set to "n", indicating that they can NOT be edited.
title {string} The title of the Wikipedia article.
link {uri} A link to the Wikipedia article.
image {uri} The URL of the image associated with the article, if it exists.
content {string} A short synopsis of the Wikipedia article.
time {string} Time item entered as displayed in event using format: HH:MM

rss objects have the following fields:


Field Name Field Value(s) Explanation
type image Describes the type of this object.
pin_id {string} ID of this pin item
timestamp {int} Date and time object was published - format UNIX timestamp.
pin_order {int} A number between 1 and 3 indicating the order the pin item is displayed. For pin items which are unpublished, this number is not meaningful (unpublished items are not displayed).
published {string} "y" if the pin item is published, "n" if the pin item is unpublished.
editable y Indicates whether the pin item can be edited through the API. For rss items this field is set to "n", indicating that they can NOT be edited.
title {string} The title of the RSS item.
link {uri} A link from the RSS item to the original article/story.
image {uri} The URL of the image associated with the RSS item, if it exists.
content {string} A short synopsis of the RSS item.

NOTE: This content may contain HTML tags
time {string} Time item entered as displayed in event using format: HH:MM

Example response to a successful pin/list request:


{
    "result":"success",
    "message":"true",
    "type":"pin",
    "action":"list",
    "version":2,
    "data":[
	    {
	        "type":"audio",
	        "pin_id":"13630093",
	        "timestamp":1315576691,
			"pin_order":1,
			"published":"y",
			"editable":"n",
	        "name":"temp_audio_file.mp4",
	        "uri":"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/audio\/201104\/phpcamiZEtemp_audio_file.mp4",
	        "embed":"<object codebase=\"http:\/\/www.apple.com\/qtactivex\/qtplugin.cab\" classid=\"clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B\" style=\"width:250px;\"><param name=\"src\" value=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/audio\/201104\/phpcamiZEtemp_audio_file.mp4\" \/><param name=\"controller\" value=\"True\" \/><param name=\"cache\" value=\"False\" \/><param name=\"autoplay\" value=\"False\" \/><param name=\"kioskmode\" value=\"False\" \/><param name=\"scale\" value=\"tofit\" \/><embed src=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/audio\/201104\/phpcamiZEtemp_audio_file.mp4\" pluginspage=\"http:\/\/www.apple.com\/quicktime\/download\/\" scale=\"tofit\" kioskmode=\"False\" qtsrc=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/audio\/201104\/phpcamiZEtemp_audio_file.mp4\" cache=\"False\" style=\"width:250px;\" controller=\"True\" type=\"video\/quicktime\" autoplay=\"False\" \/><\/object>"
	    },
	    {
	        "type":"video",
	        "pin_id":"13630092",
	        "timestamp":1315576686,
			"pin_order":2,
			"published":"y",
			"editable":"n",
	        "uri":"",
	        "name":"movie.mov",
	        "embed":"<object codebase=\"http:\/\/www.apple.com\/qtactivex\/qtplugin.cab\" classid=\"clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B\" style=\"width: 400px; height: 300px;\"><param name=\"src\" value=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/video\/201011\/phpXTqi81movie.mov\" \/><param name=\"controller\" value=\"True\" \/><param name=\"cache\" value=\"False\" \/><param name=\"autoplay\" value=\"True\" \/><param name=\"kioskmode\" value=\"False\" \/><param name=\"scale\" value=\"tofit\" \/><embed src=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/video\/201011\/phpXTqi81movie.mov\" pluginspage=\"http:\/\/www.apple.com\/quicktime\/download\/\" scale=\"tofit\" kioskmode=\"False\" qtsrc=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/video\/201011\/phpXTqi81movie.mov\" cache=\"False\" style=\"width: 400px; height: 300px;\" controller=\"True\" type=\"video\/quicktime\" autoplay=\"False\" \/><\/object>"
	    },
	    {
	        "type":"image",
	        "pin_id":"13630091",
	        "timestamp":1315576678,
			"pin_order":3,
			"published":"y",
			"editable":"y",
	        "embed":"<img src=\"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/image\/201104\/phpz6hzVr_thumb_IMG_20110324_135842.jpg\"  width=\"240\"  height=\"320\"  border=\"0\" style=\"border: 1px solid #999999;\">",
	        "uri":"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/image\/201104\/phpz6hzVrIMG_20110324_135842.jpg",
	        "uri_height":"2592",
	        "uri_width":"1944",
	        "uri_thumb":"http:\/\/cdn.cloudfiles.mosso.com\/c71712\/media\/image\/201104\/phpz6hzVr_thumb_IMG_20110324_135842.jpg",
	        "caption":"",
	        "name":"IMG_20110324_135842.jpg",
	    },
	    {
	        "type":"guest_comment",
	        "pin_id":"13630089",
	        "timestamp":1315576620,
			"pin_order":1,
			"published":"n",
			"editable":"y",
	        "author_name":"Bob ",
	        "source":"",
	        "comment":"Test comment from a guest. ",
	    },
	    {
	        "type":"instagram",
	        "pin_id":"13630094",
	        "timestamp":1315576620,
			"pin_order":1,
			"published":"n",
			"editable":"n",
	        "author_name":"Gaspar",
	        "link":"http://instagr.am/p/UlyJMZGeQJ/",
	        "images": {
	             "standard_resolution" : {
	                  "width" : 612,
	                  "height" : 612,
	                  "url" : "http://distilleryimage1.s3.amazonaws.com/d8e8643860bc11e2b60722000a9f09f0_7.jpg"
	             }
	         }
	        "comment":"#keepcalmandcarryon #keepcalmandcallbatman #batman #iphonesia",
	    },
	    {
	        "type":"wikipedia",
	        "pin_id":"13630095",
	        "timestamp":1315576630,
			"pin_order":1,
			"published":"n",
			"editable":"n",
	        "title":"Batman",
	        "link":"http://en.wikipedia.org/wiki/Batman",
	        "image":"http://upload.wikimedia.org/wikipedia/en/thumb/a/a7/Batman_Lee.png/100px-Batman_Lee.png",
	        "content":"Batman is a fictional character, a comic book superhero created by artist Bob Kane and writer Bill Finger.",
	    },
	    {
	        "type":"rss",
	        "pin_id":"13630096",
	        "timestamp":1315576641,
			"pin_order":1,
			"published":"n",
			"editable":"n",
	        "title":"'Last Stand' star Schwarzenegger talks gun control",
	        "link":"http://news.yahoo.com/last-stand-star-schwarzenegger-talks-gun-control-144207383.html",
	        "image":"http://media.zenfs.com/en_us/News/ap_webfeeds/4ce7d1980e04d302260f6a7067002a5b.jpg",
	        "content":"<p><a href='http://news.yahoo.com/last-stand-star-schwarzenegger-talks-gun-control-144207383.html'></a>LOS ANGELES (AP) — Arnold Schwarzenegger doesn't think there's a parallel between film and real-world gun violence.</p><br clear='all'>",
	    },
	    {
	        "type":"host_comment",
	        "pin_id":"13630088",
	        "timestamp":1315576600,
			"pin_order":1,
			"published":"n",
			"editable":"y",
	        "author_name":"Brownjord Owner",
	        "author_avatar":"",
	        "comment":"Test content from the host ",
	    },
	    {
	        "type":"tweet",
	        "pin_id":"14540614",
	        "timestamp":1345659003,
			"pin_order":1,
			"published":"n",
			"editable":"n",
	        "author_name":"coveritlive",
	        "author_avatar":"http:\/\/a0.twimg.com\/profile_images\/2262955395\/CIL_Twitter_avatar_normal.png",
	        "comment":"Join the <a target=_blank href='https:\/\/twitter.com\/Cricketnation'>Cricketnation<\/a> <a target=_blank href='https:\/\/twitter.com\/search\/%23LiveChat'>#LiveChat<\/a> with <a target=_blank href='https:\/\/twitter.com\/search\/%23NiceMoves'>#NiceMoves<\/a> & <a target=_blank href='https:\/\/twitter.com\/search\/%23SYTYCD'>#SYTYCD<\/a> dancer Chris Koehl <a target=_blank href='https:\/\/twitter.com\/D8ChrisK'>@D8ChrisK<\/a> on Facebook at 2 pm ET <a target=_blank href='http:\/\/t.co\/b4HMdd5E'>on.fb.me\/R0yXws<\/a>",
	        "tweet_data": {
	            "id":"238327830860161024",
	            "name":"CoveritLive",
	            "username":"coveritlive",
	            "created_at":"Wed, 22 Aug 2012 17:32:37 +0000"
	        }
		}
    
	]
}

pin/list Error Responses

A variety of error responses (in addition to the common error responses) to pin/list requests, and instructions on how to rectify them:

result response message response solution
missing_status_param Required parameter empty: status. Ensure the status parameter is present for pin/list requests.
invalid_status_param Status parameter contains invalid values. Ensure the status parameter only contains valid values (pipe delimited list, which can include 'published' and 'unpublished').