API version: 0.7 (26/11/2011)
Changelog:
v0.7 (26/11/2011) - articles are now searchable
v0.6 (20/11/2011) - option of getting icould-hosted videos or YouTube-hosted videos
v0.5 (24/10/2011) - API now also works over SSL (https://icould.com/api)
v0.4 (22/05/2011) - videos now served by YouTube
v0.3 (18/11/2010) - addition of API keys
icould exposes data about its videos via an Application Programming Interface (API). This document is the official reference for that functionality.
An API Key is required in order to access the icould API. Please contact icould.com through the website to acquire an API key.
All API calls should be made to the same URL,http://icould.com/apiReturns videos and/or articles that match a specified query.
key - Your API key (required)url - Your website's URL, as stated when requesting your API key. This value must be url-encoded. (required)type - Search type (video / article / both). (optional, defaults to video)s - Search term (optional)page - Page number (optional, defaults to 1)results - Results per page (optional, defaults to 10, capped at 50). If type=both,the number of results returned may be up to double this value, as it applies to the number of videos and number of articles.cat - Category ID. Comma-separated IDs perform an OR search, plus-separated IDs perform an AND search (optional)The API will return an XML RSS document with the parent DOM element <channel>. A child element <total_results> contains the total number of videos & articles that match the search query. Two more elements <total_video_results> and <total_article_results> are also returned. Be aware that results are paginated, depending on the page and results parameters.
If results are found, the <channel> element will contain any number of <item> elements. Each <item> element will contain the following child elements:
<guid> - article/video ID<link> - link to the article/video's page on icould.com<title> - the video's title (name + job title), or article title<description> - a brief summary<pubDate> - date the video was uploaded, or the article was created<video_src> - direct URL to the MP4 video file (for videos only)<video_width> - width in pixels of the video (for videos only)<video_src_height> - height in pixels of the video (for videos only)<video_embed_height> - height in pixels of the video player (includes controls) (for videos only)<thumbnail_large> - URL of large thumbnail for video (for videos only)<thumbnail_small> - URL of small thumbnail for video/article (should be 144x81px)<item> elements, and the <total_results> element will contain the value 0.
This shows how to use your API key and URL when performing an API call:
http://icould.com/api?s=radio&cat=548,202&key=b758c434bdd396b1a444db390503f85b-4ce49bb91f7f8&url=http%3A%2F%2Fwww.test.com
NB: All further examples omit the required "key" and "url" parameters for brevity.
Returns information about one article/video, including embed code for video player, or the article content.
key - Your API key (required)url - Your website's URL, as stated when requesting your API key. This value must be url-encoded. (required)id - Article/Video IDyt - Whether to get YouTube or icould Flash video. 1 = get YouTube-hosted version; 0 = get icould-hosted version (for videos only)The same XML elements are returned as for a search (documented above), with two additional elements:
<embed_code> - HTML code to embed the video player, or the HTML of the article<youtube_id> - The ID string for the YouTube video (if yt=1 or yt is not set) (for videos only)NB: This example omits the required "key" and "url" parameters for brevity.
Returns a hierarchical tree of categories, along with the number of videos in each category.
key - Your API key (required)url - Your website's URL, as stated when requesting your API key. This value must be url-encoded. (required)list_cats - must be present and not emptyThe API will return an XML document with the parent element <categories>. There will be 2-3 levels of <category> child elements.
If a category has child elements, it will only contain a name attribute, indicating the category name.
If a category has no child elements, it will contain the following attributes:
name - the category nameid - the category ID (to be passed in search queries)count - the number of videos in the categoryNB: This example omits the required "key" and "url" parameters for brevity.