Developer Guide

API
See our technology in action - www.medioh.tv

Enter your information below to receive an API key free for up to 1000 requests! per month or contact us to request a license.

We promise not to spam your inbox or share your information with anyone.

Your name:
Company:
E-mail:

medioh.tv exposes set of APIs for accessing our vast video directory. While the main function of our API is video search, we also expose other functions to enrich the end-user experience. Please visit out wiki at http://wiki.medioh.com/index.php/Developer_API for the full functionality of our APIs.

Results are returned in RSS 2.0 syndication format with Media RSS extensions. Queries should be made as GET requests with all parameters passed via the query string (e.g. /videos.rss?param1=value1&param2=value2)

Additionally, JSON representations are available for all API features.

Video Search API

The base URL for our video search API is:

http://medioh.tv/videos.rss

Alternatively, a JSON representation is available at:

http://medioh.tv/videos.json

The following parameters are supported, and may be mixed and matched in any combination you desire (with a few noted caveats):

key
Your API key, provided by us. If you don’t already have one, enter your e-mail address in the box to your right to request one.
query
Perform a search query. The value passed to this parameter should be a word or phrase to search for.
tags
Search within the specified list of tags (i.e. categories). Separate tags with commas.
page
Retrieve results for the given page number. The first page is 1.
per_page
Return the specified number of results per page. The maximum is 100.
order
Specify the order results should be returned in. The value must be one of the following:
  • relevance – Relevance of the result to the given search term (must specify a query)
  • date – Ordered from newest to oldest
  • quality – Ordered by video bitrate from highest to lowest
  • resolution – Ordered by video resolution from highest to lowest
  • duration – Ordered by the duration of the content from longest to shortest
  • length – Ordered by the length of the content in bytes from longest to shortest
  • views – Ordered by total number of views from highest to lowest
  • ranking – Ordered by user ranking from highest to lowest
ascending
If the value for this parameter is “true”, invert the order in which results are returned (e.g. oldest to newest, lowest bitrate to highest, etc.)
explicit
If this is set to “true” / “false”, only content marked as explicit / non-explicit is returned.
copyrighted
If set to “true”, only content with known copyright information is returned.
video_format
A comma separated list of video codecs (i.e. FOURCC codes, see fourcc.org) that results should include. Videos which do not match the specified codecs will be omitted. The following are some examples of FOURCC codes for video codecs:
  • avc1, h264 – H.264, i.e. MPEG-4 AVC
  • mp4v – MPEG-4
  • wmv3, wmv2, wmv1 – Windows Media Video 9, 8, and 7 respectively
  • svq3 – Apple QuickTime 5 (i.e. Sorensen Video 3)
  • mpg2 – MPEG-2
  • flv1 – Flash Video, i.e. Sorensen Spark / H.263
  • div3, divx, dx50 – DivX 3, DivX 4+, and DivX 5 respectively
  • xvid – XviD
audio_format
A comma separated list of audio codecs (i.e. FOURCC codes, see fourcc.org) that results should include. Videos which do not encode audio with the specified codecs will be omitted. The following are some examples of FOURCC codes for audio codecs:
  • mp4a – MPEG-4 audio
  • 85, .mp3 – MP3, i.e. MPEG-1 Layer 3 audio
  • 353 – DivX Audio Compressor
  • wma1, wma2 – Windows Media Audio 1 and 2 respectively
  • qdm2, qdmc – Apple QuickTime Audio (i.e. QDesign Music Codec)
  • alac – Apple Lossless Audio Codec
  • raw, twos, sowt – Uncompressed PCM
language
A comma separated list of two letter language codes (see ISO 639-1). Only videos in the specified languages will be returned.
sites, exclude_sites
A comma separated list of sites that are either required or excluded. For example, exclude_sites=youtube,dailymotion will not return videos from either site.
min_width, max_width, min_height, max_height
Specify the minimum and/or maximum dimensions of a video in pixels.
min_duration, max_duration
Specify a minimum and/or maximum duration of a video in seconds.
min_length, max_length
Specify a minimum and/or maximum length of a video in bytes.
min_views, max_views
Specify the minimum and/or maximum number of user views.
min_ranking, max_ranking
Specify the minimum and/or maximum user ranking (ranges from 0.0 to 1.0).
min_date, max_date
Specify the minimum and/or maximum publish date.
min_bitrate, max_bitrate
Specify the minimum and/or maximum bitrate (bits/second).

Channel Search API

Channels are feeds of multiple videos created by a content producer.

The base URL for our video search API is:

http://medioh.tv/channels.rss

Alternatively, a JSON representation is available at:

http://medioh.tv/channels.json

The following parameters are supported:

key
Your API key, provided by us. If you don’t already have one, enter your e-mail address in the box to your right to request one.
query
Perform a search query. The value passed to this parameter should be a word or phrase to search for.
tags
Search within the specified list of tags (i.e. categories). Separate tags with commas.
page
Retrieve results for the given page number. The first page is 1.
per_page
Return the specified number of results per page. The maximum is 100.
explicit
If set to “true” / “false”, only content marked as explicit / non-explicit is returned.
video_format
A comma separated list of video codecs (i.e. FOURCC codes, see fourcc.org) that results should include. Videos which do not match the specified codecs will be omitted. The following are some examples of FOURCC codes for video codecs:
  • avc1, h264 – H.264, i.e. MPEG-4 AVC
  • mp4v – MPEG-4
  • wmv3, wmv2, wmv1 – Windows Media Video 9, 8, and 7 respectively
  • svq3 – Apple QuickTime 5 (i.e. Sorensen Video 3)
  • mpg2 – MPEG-2
  • flv1 – Flash Video, i.e. Sorensen Spark / H.263
  • div3, divx, dx50 – DivX 3, DivX 4+, and DivX 5 respectively
  • xvid – XviD
language
A comma separated list of two letter language codes (see ISO 639-1). Only videos in the specified languages will be returned.
sites, exclude_sites
A comma separated list of sites that are either required or excluded. For example, exclude_sites=youtube,dailymotion will not return videos from either site.

Recommendations API

medioh.tv exposes an API for obtaining both recommendations for individual videos and personalized recommendations based on a set of weighted videos. The URL for video recommendations is present for all videos returned from Medioh API results in the <medioh:recommendations> tag. You can also access it directly at:

http://medioh.tv/videos/<video_id>/recommendations.rss

...where <video_id> is a valid video ID in the Medioh guide.

Alternatively, a JSON representation is available at:

http://medioh.tv/videos/<video_id>/recommendations.json

Personalized recommendations are generated through the following URL:

http://medioh.tv/recommendations.rss?weights=<video1_id>:<score1>,<video2_id>:<score2>,...

...where is a valid video ID in the Medioh guide, and score is a floating point value in the range -1 to 1. Positive values represent a positive ranking, negative values represent a negative ranking. One of the simplest approaches is specifying 1.0 for all videos a given user has watched.

Alternatively, a JSON representation is available at:

http://medioh.tv/recommendations.json?weights=<video1_id>:<score1>,<video2_id>:<score2>,...

The recommendations API will automatically exclude all videos used as input. Additionally, the following parameters may be specified:

key
Your API key, provided by us. If you don’t already have one, enter your e-mail address in the box to your right to request one.
page
Retrieve results for the given page number. The first page is 1.
per_page
Return the specified number of results per page. The maximum is 100.
explicit
If set to “true” / “false”, only content marked as explicit / non-explicit is returned.
video_format
A comma separated list of video codecs (i.e. FOURCC codes, see fourcc.org) that results should include. Videos which do not match the specified codecs will be omitted. The following are some examples of FOURCC codes for video codecs:
  • avc1, h264 – H.264, i.e. MPEG-4 AVC
  • mp4v – MPEG-4
  • wmv3, wmv2, wmv1 – Windows Media Video 9, 8, and 7 respectively
  • svq3 – Apple QuickTime 5 (i.e. Sorensen Video 3)
  • mpg2 – MPEG-2
  • flv1 – Flash Video, i.e. Sorensen Spark / H.263
  • div3, divx, dx50 – DivX 3, DivX 4+, and DivX 5 respectively
  • xvid – XviD
©2007-08 Medioh, Inc.