icould API Documentation

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, API_URL
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.

An important note about caching

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.


Search

Returns videos and/or articles that match a specified query.

Input Parameters

Response

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:

If no matches are found, the XML document will contain no <item> elements, and the <total_results> element will contain the value 0.

Examples

This shows how to use your API key and URL when performing an API call:

API_URL?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.


Show Article/Video Information

Returns information about one/multiple article(s)/video(s), including embed code for video player, or the article content.

Input Parameters

Response

The same XML elements are returned as for a search (documented above), with two additional elements:

Example

NB: This example omits the required "key" and "url" parameters for brevity.


List Categories

Returns a hierarchical tree of categories, along with the number of videos in each category.

Input Parameters

Response

The 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:

Example

NB: This example omits the required "key" and "url" parameters for brevity.


List SOC Codes

Returns a list of SOC codes.

Input Parameters

Response

The 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:

Example

NB: This example omits the required "key" and "url" parameters for brevity.


Show LMI Infographic & videos for a SOC code

Returns HTML embed code for employment information about a job title (SOC code) and a list of videos associated with the SOC code.

Input Parameters

Response

Example

NB: This example omits the required "key" and "url" parameters for brevity.