JSON Feed

The Vidcaster JSON feed API is a simple but powerful feed-based API for creating queries to fetch Vidcaster video content for use in third-party applications.

CONSTRUCTING A REQUEST<br/ > You can fetch a simple JSON request with no query terms by simply visiting the JSON endpoint. On Vidcaster powered sites the JSON endpoint is:

Endpoint URL Structure:
http://[yourdomain.com]/feeds/json/

Live Example:
http://www.vidcaster.com/feeds/json/

FILTERING REQUESTS BY GROUP
The above default feed returns *all* videos from the site. It's very easy to filter JSON requests by a Vidcaster "Group" (also known as Category for self-serve accounts, groups can have custom labels such as "Chapter" or "Show" for Enterprise accounts).

To filter the JSON request by a specific group, simply insert a group short name in the URL in this format:

Filter by Group URL Structure:
http://[yourdomain.com]/feeds/[group_short_name]/json/

Live Example:
http://www.vidcaster.com/feeds/tutorials/json/

FILTER REQUESTS BY VIDEO SHORTCODE
If you know the Vidcaster "Shortcode" of one or more videos, you can filter the JSON response by video shortcode. This is useful to drill down to metadata for a specific video without loading data for other video contents.

You may specify one or more "shortcode" in the querystring of the standard JSON request. For example,

Shortname Query Structure:
http://[yourdomain.com]/feeds/json/?shortcode=[shortcode1]&shortcode=[shortcode2]

Live Example:
http://www.vidcaster.com/feeds/json/?shortcode=e6Mf&shortcode=gGba

SPECIFYING CUSTOM THUMBNAILS
JSON requests support the generation of multiple, custom thumbnail sizes. This is highly useful for mobile applications on devices with limited image processing capabilities. For example:

Custom Thumbnail URL Query Structure:
http://[yourdomain.com]/feeds/json/?thumbnail=[width in px]x[height in px]&thumbnail=[width in px]x[height in px]

Live Example:
http://www.vidcaster.com/feeds/json/?thumbnail=101x75&thumbnail=450x334

Additional custom thumbnail notes:

  • Generating custom thumbnails for the first time on many videos may take up to one minute on first request, subsequent requests include cached thumbnails for consistent performance.
  • You can add up to 5 discrete thumbnail sizes. The thumbnails are guaranteed to return a thumbnail of the specified size. The thumbnails will intelligently crop in order to maintain aspect ratio while still maintaining desired output size.
  • In the returned JSON feed, a custom thumbnail is passed as a key/value where key is equal to "thumbnail:[width]x[height]" and value is the URI of the thumbnail image file. For example, a thumbnail requested at 101 pixel width by 75 pixel height will result in a key of "thumbnail:101x75".
  • Default "thumbnail" key/value entry is included in all feeds and is sized up to 120x68 but reduced proportionately as needed to maintain aspect ratio. You may safely ignore this entry if not needed.
  • Please note that errors in the query string requests for "thumbnail" will *not* result in an error message, and will instead revert to default settings in the case of malformed requests in order to prioritize user experience above technical accuracy.

SPECIFYING CUSTOM TRANSCODE TYPE
The JSON feed output can be filtered by Transcode Format type. The Format should be passed as a querystring variable in shortname format, examples include "h264", "h264br800", and "hls-index-6-bitrates". For example:

Custom Transcode Format Query Structure:
http://[yourdomain.com]/feeds/json/?format=[format_shortname]

Live Example:
http://www.vidcaster.com/feeds/json/?format=h264br800

Additional custom transcode notes:

  • Please note that errors in the query string requests for "format" will *not* result in an error message, and will instead revert to default settings in the case of malformed requests in order to prioritize user experience above technical accuracy. Please double check to make sure the output of the feed returns the desired attributes and is not returning defaults. (For example, the default fallback video URL is a direct mp4 file and not an m3u8 digest for Apple adaptive streaming.)

COMBINING FILTERS
You can chain all of the above filters to combine them in one single request. For example, to return videos in the "Tutorial" category with a custom thumbnail size of 450x334 with a link to a 800 kbps H264 bitrate returned in the feed you could combine all of these into one request:

Live Example:
http://www.vidcaster.com/feeds/tutorials/json/?format=h264br800&thumbnail=450x334