API version: 1.5 (10/01/2019)
Changelog:
v1.5 (10/01/2019) - updates to the API, bugfixes to support the new icould website and updated the documentation
v1.4 (11/03/2014) - added LMI infographic for SOC codes, and option to list SOC codes
v1.3.1 (19/12/2013) - bugfix for some video thumbnails
v1.3 (11/07/2013) - option of getting video transcript/captions
v1.2 (29/03/2013) - support for API keys that are restricted to retrieving only certain content types
v1.1 (03/01/2013) - option of getting comma-separated list of all <categories> for all videos/articles returned.
v1.0 (24/12/2012) - option of getting videos/articles added since a specified date (facilitates cache-busting). Requesting data for an individual article/video now returns a comma-separated list of all <categories> with which it is tagged.
v0.9 (07/11/2012) - option of getting short or long versions of videos
v0.8 (01/10/2012) - option to submit comma-separated IDs to retrieve information for multiple videos/articles
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 and articles 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/api
The API is entirely HTTP-based, using the HTTP GET method (i.e. parameters passed in the URL), and returns XML data.
The search API response is loosely-based on the RSS protocol, so the API can be used as an RSS feed for specific videos. This also means many browsers will only show minimal response information when displaying an API URL. Viewing the document source will show the full response data.
Examples of how to use the API are shown inline.
icould content tends to remain static once it has been added to the site. Also, content is not added so frequently as to change between pageviews of your site. Thus, you are STRONGLY advised to cache the responses you retrieve from the icould API, and use your local cache when generating your HTML pages which include icould content. In any case, you should be caching the HTML generated by your site scripts, to reduce the processing time of your server when rendering and serving pages.
You should DEFINITELY cache the data returned for a specific video or article, as this will rarely, if ever, be updated. Under no circumstances should you query the icould API for a video's embed code each and every time a visitor browses to your page containing the video.
v1.0 of the icould API introduced new added_since functionality that allows you to check if any new content has been added to the site. You should thus be safe to rely on your cached data as long as no relevant new content has been added to the API. For example, if no new videos have been added since you last cached the API's response, you would get the same response when searching for videos by search term or category ID, and the video's embed code would be the same. You can check for articles/videos added since a specific date for category and/or search term requests, as well as with no search parameters.
Returns 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). If set to both, video results will be returned first, followed by article results; however this will be on a page-by-page basis (so each page may return some videos and then some articles). You are advised against using the both option.video_length - Video length (long / short). (optional, defaults to long)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)added_since - GMT date-time in SQL format YYYY-MM-DD HH:MM:SS - returns only content added since this timestamp (optional). If this flag is set, and no search term (parameter "s") has been provided, results will be returned in reverse chronological order.show_categories - if set, a list of all videos'/articles' categories will be included in the response.mp4 - if set, returns the video file URLThe 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_lengths_available> - whether long, short, or both video lengths are available. (for videos only)<video_length> - video length returned (long or short). NB - if the short version is requested, but only the long version exists, it will return the long version; and vice versa. This element will allow you to check which version was returned. (for videos only)<video_src> - direct URL to the page containing the video, whether on icould.com, or YouTube. (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)<categories> - A list of categories that this article/video is tagged with. (only if show_categories is present in the request)<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.
http://icould.com/api?s=radio - search for videos matching term "radio"http://icould.com/api?s=radio&type=article - search for articles matching term "radio"http://icould.com/api?s=radio&type=both - search for articles AND videos matching term "radio"http://icould.com/api?s=beglin - search for videos matching term "beglin" - will perform a phonetic search if no exact matches foundhttp://icould.com/api?s=office&page=2&results=30 - search for videos matching term "radio", but only get results 31-60 (i.e. page 2, with 30 results per page)http://icould.com/api?cat=289 - search for videos in category 289http://icould.com/api?cat=289&video_length=short - search for videos in category 289, and return only the short versionshttp://icould.com/api?cat=289+291 - search for videos in category 289 AND category 291http://icould.com/api?s=office&cat=289 - search for videos matching "office" in category 289http://icould.com/api?s=office&cat=289,291 - search for videos matching "office" in category 289 OR category 291http://icould.com/api?s=office&cat=289+291 - search for videos matching "office" in category 289 AND category 291http://icould.com/api?type=articles&added_since=2012-12-15 12:00:00 - search for articles added since noon (GMT) on 15th December 2012. Latest articles appear at the top of the resultshttp://icould.com/api?cat=289+291&added_since=2009-12-20 - search for videos matching in category 289 AND category 291, added since midnight (GMT) on 20th December 2009. Latest videos appear at the top of the resultshttp://icould.com/api?cat=289&show_categories=1 - search for videos in category 289, and show all related categories for each video returnedhttp://icould.com/api&type=video&id=5600&yt=0&mp4=1 - returns video information and also a link to the video fileReturns information about one/multiple article(s)/video(s), 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 ID (you can also send comma-separated IDs)yt - Whether to get YouTube or icould Flash video. 1 = get YouTube-hosted version; 0 = get icould-hosted version (for videos only)video_length - Whether to get the long, or short versions (for videos only). NB - if the short version is requested, but only the long version exists, it will return the long version; and vice versa. (optional, defaults to long)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. This element will be contain the embed code for the short version of the video if the video does not have a long version, and vice versa.<youtube_id> - The ID string for the YouTube video (if yt=1 or yt is not set) (for videos only). This element will contain the YouTube ID of the short version of the video if the video does not have a long version, and vice versa.<categories> - A comma-separated list of category IDs that this article/video is tagged with.NB: This example omits the required "key" and "url" parameters for brevity.
http://icould.com/api?id=10419 - get info about article/video ID 10419, as well as the embed code for the article content or video playerhttp://icould.com/api?id=10419&video_length=short - get info about video ID 10419, as well as the embed code for the short version of the video playerReturns 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/articles in the category (however, these values are inaccurate)NB: This example omits the required "key" and "url" parameters for brevity.
http://icould.com/api?list_cats=1 - show a hierarchical list of all categoriesReturns a list of SOC codes.
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_soc_codes - must be present and not emptyThe API will return an XML document with the parent element <soc_codes>. There is one level of <soc_code> child elements, with the following attributes:
title - the SOC code job titleid - the SOC code IDNB: This example omits the required "key" and "url" parameters for brevity.
http://icould.com/api?list_soc_codes=1 - show a list of all SOC codesReturns HTML embed code for employment information about a job title (SOC code) and a list of videos associated with the SOC code.
key - Your API key (required)url - Your website's URL, as stated when requesting your API key. This value must be url-encoded. (required)soc - SOC code (required)<embed_code> - HTML code to embed the video player, or the HTML of the article. This element will be contain the embed code for the short version of the video if the video does not have a long version, and vice versa.<videos> - Returns a list of videos separated as video nodes within it.NB: This example omits the required "key" and "url" parameters for brevity.
http://icould.com/api?soc=9271 - get HTML embed code for employment infographic about SOC code 9271 (hospital porter)