Video Feed Types

This page describes several different types of video feeds that can be retrieved using the YouTube API. A video feed contains a list of videos that would be displayed in a list on your site. You can use standard API query parameters to customize the number of videos that you retrieve.

Video feeds return a collection of video entries. In turn, each video entry contains information about a specific video in the video feed’s result set.

This page explains how to retrieve the following types of video feeds:

• Videos Feeds
• Related videos feed
• Special feeds
• Video Search

Videos Feeds

The API returns a videos feed in response to a request to a specfic video feed or a search search request. To obtain a result set listing all the videos in our catalog, send an API request to the following URL:

http://api.movieclips.com/v2/videos

Video feed requests can use any of the standard or custom query parameters. For example, the following URL requests all videos that are of type mashup, starting with the 20th result and returning 10 results:

http://api.movieclips.com/v2/videos?
  filter_by=mashup
  &offset=20
  &count=10

Related videos feed

The related videos feed contains a list of videos that are related to another video. Movieclips algorithmically selects the set of related videos.

Each video entry in an API response contains a series of <link> tags. The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007/#video.related identifies the URL for retrieving other videos related to that video entry. (The <link> tag’s href attribute identifies the URL.)

<link href="http://api.movieclips.com/v2/videos/ADSBW/related"
  type="application/atom+xml"
  rel="http://gdata.youtube.com/schemas/2007#video.related" />

Note

The reference to http://gdata.youtube.com/schemas/2007 is not a typo. When possible we will leverage methodolgies that people may already be familiar with instead of re-inventing our own just for the sake of doing so.

Special feeds

Special feeds contain lists of videos that were selected movieclips.com to highlight their importance. You can programatically access the list of available special-feeds at the following url:

http://api.movieclips.com/v2/special-feeds

To retrieve a special feed, send an HTTP GET request to the URL associated with that feed. The following table identifies the URL associated with each standard feed:

Name	Feed Id	URL and Description
Clip of the Day	clip-of-the-day	URL: http://api.movieclips.com/v2/special-feeds/clip-of-the-day Description: This feed contains videos that were desginated “Clip of the Day”.
Recently Added	recently-added-videos	URL: http://api.movieclips.com/v2/special-feeds/recently-added-videos Description: This feed contains videos that were recently added to our library.
Now In Theaters	in-theaters	URL: http://api.movieclips.com/v2/special-feeds/in-theaters Description: This feed contains videos from movies that are now in theaters.
Opening this Week	opening-this-week	URL: http://api.movieclips.com/v2/special-feeds/opening-this-week Description: This feed contains videos from movies that are opening this week.
New on DVD	new-on-dvd	URL: http://api.movieclips.com/v2/special-feeds/new-on-dvd Description: This feed contains videos from movies that are new on dvd.
Coming Soon	coming-soon	URL: http://api.movieclips.com/v2/special-feeds/coming-soon Description: This feed contains videos from movies that are opening soon.

Video Search

The search feature of the API allows users to query the MOVIECLIPS data in many different ways. The base url for searching videos is:

http://api.movieclips.com/v2/search/videos

The simplest type of search is to just append the q custom query parameter to the base url. For example, using the search term car:

http://api.movieclips.com/v2/search/videos?q=car

Results may include videos that have been tagged with the value car as either a setting or a prop; and/or have car in the movie title or video title; or may have used the term in the dialogue.

Narrowing your search

You can also narrow the set of videos that is to be searched by adding filters to the urls using the concept of Matrix URLs.

Note

Please notice that the filtering of search results is not done the same way as filtering of videos throught the /v2/videos resouces which uses the filter_by custom query parameter.

As an example, if you wanted to search videos that are in the setting of village where a arrow was used as a prop and the term robin hood is relevant; you would make an API request to the following url:

http://api.movieclips.com/v2/search/videos/setting=village~prop=arrow?q=robin%20hood

You can filter your results by pairing up our valid search filter keys with the desired term. For best results we recommed that you pair your filter keys with terms in their corresponding resource URIs when appropriate.

Valid Search Filter Keys

Key Name	Reference URL and Description
movie	REF URL: http://api.movieclips.com/v2/movies Description: Use this key to filter within movie titles.
actor	REF URL: http://api.movieclips.com/v2/people/actor Description: Use this key to filter within actor names.
director	REF URL: http://api.movieclips.com/v2/people/director Description: Use this key to filter within director names.
producer	REF URL: http://api.movieclips.com/v2/people/producer Description: Use this key to filter within producer names.
role-name	REF URL: http://api.movieclips.com/v2/people/role-name Description: Use this key to filter within role names(e.g. batman).
character-type	REF URL: http://api.movieclips.com/v2/people/character-type Description: Use this key to filter within character types.
action	REF URL: http://api.movieclips.com/v2/metadata/action Description: Use this key to filter within actions.
editors-choice	REF URL: http://api.movieclips.com/v2/metadata/editors-choice Description: Use this key to filter within editor’s choice.
primary-genre	REF URL: http://api.movieclips.com/v2/metadata/primary-genre Description: Use this key to filter within primary genres.
secondary-genre	REF URL: http://api.movieclips.com/v2/metadata/secondary-genre Description: Use this key to filter within secondary genres.
primary-occasion	REF URL: http://api.movieclips.com/v2/metadata/primary-occasion Description: Use this key to filter within primary occasions.
secondary-occasion	REF URL: http://api.movieclips.com/v2/metadata/secondary-occasion Description: Use this key to filter within secondary occasions.
prop	REF URL: http://api.movieclips.com/v2/metadata/prop Description: Use this key to filter within props.
setting	REF URL: http://api.movieclips.com/v2/metadata/setting Description: Use this key to filter within settings.
studio	REF URL: http://api.movieclips.com/v2/metadata/studio Description: Use this key to filter within studios.
theme	REF URL: http://api.movieclips.com/v2/metadata/theme Description: Use this key to filter within themes.
mood	REF URL: http://api.movieclips.com/v2/metadata/mood Description: Use this key to filter within moods.
year	REF URL: http://api.movieclips.com/v2/metadata/mood Description: Use this key to filter for videos from movies released in a specified year.
movie-freebase-guid	REF URL: http://wiki.freebase.com/wiki/Guid EXAMPLE URL: http://api.movieclips.com/v2/movies/%239202a8c04000641f800000000026edaa/videos?id_type=movie-freebase-guid Description: The Freebase supplied guid of the movie you want videos of. ID value must be url encoded.
movie-freebase-mid	REF URL: http://wiki.freebase.com/wiki/Mid EXAMPLE URL: http://api.movieclips.com/v2/movies/02fwfb/videos?id_type=movie-freebase-mid Description: The Freebase supplied guid of the movie you want videos of. ID value must be url encoded. Please note that you cannot include the namespace identifier "/m/" in your request. If you include this you will generate a 404 response.
movie-amg-id	REF URL: http://developer.rovicorp.com EXAMPLE URL: http://api.movieclips.com/v2/movies/V%2B%2B%2B133443/videos?id_type=movie-amg-id Description: The Rovi/AMG supplied id of the movie you want videos of. ID value must be url encoded.
movie-cosmo-id	REF URL: http://developer.rovicorp.com EXAMPLE URL: http://api.movieclips.com/v2/movies/1237212/videos?id_type=movie-cosmo-id Description: The Freebase guid of the movie you want videos of. ID value must be url encoded.
movie-imdb-id	REF URL: http://imdb.com EXAMPLE URL: http://api.movieclips.com/v2/movies/tt0109045/videos?id_type=movie-imdb-id Description: The IMDB supplied id of the movie you want videos of. ID value must be url encoded.
movie-netflix-id	REF URL: http://netflix.com EXAMPLE URL: http://api.movieclips.com/v2/movies/221126/videos?id_type=movie-netflix-id Description: The IMDB supplied id of the movie you want videos of. ID value must be url encoded.
upc-code-id	REF URL: http://en.wikipedia.org/wiki/Universal_Product_Code EXAMPLE URL: http://api.movieclips.com/v2/movies/043396215634/videos?id_type=upc-code-id Description: The 12 digit UPC code of the DVD or Blue-Ray
person-freebase-guid	REF URL: http://wiki.freebase.com/wiki/Guid EXAMPLE URL: http://api.movieclips.com/v2/people/actor/%239202a8c04000641f80000000001aca5c/videos?id_type=person-freebase-guid Description: The Freebase supplied guid of the person (in this case an actor) you want videos of. ID value must be url encoded.
person-freebase-mid	REF URL: http://wiki.freebase.com/wiki/Mid EXAMPLE URL: http://api.movieclips.com/v2/people/actor/01pllx/videos?id_type=person-freebase-mid Description: The Freebase supplied guid of the person (in this case an actor) you want videos of. ID value must be url encoded. Please note that you cannot include the namespace identifier "/m/" in your request. If you include this you will generate a 404 response.
person-amg-id	REF URL: http://developer.rovicorp.com EXAMPLE URL: http://api.movieclips.com/v2/people/actor/P%2B%2B%2B%2B65046/videos?id_type=person-amg-id Description: The Rovi/AMG supplied id of the person (in this case an actor) you want videos of. ID value must be url encoded.
person-imdb-id	REF URL: http://imdb.com EXAMPLE URL: http://api.movieclips.com/v2/people/actor/nm0000221/videos?id_type=person-imdb-id Description: The IMDB supplied id of the person (in this case an actor) you want videos of. ID value must be url encoded.
person-freebase-guid	REF URL: http://wiki.freebase.com/wiki/Guid EXAMPLE URL: http://api.movieclips.com/v2/people/editor/%239202a8c04000641f80000000000045b9/videos?id_type=person-freebase-guid Description: The Freebase supplied guid of the person (in this case an editor) you want videos of. ID value must be url encoded.
person-freebase-mid	REF URL: http://wiki.freebase.com/wiki/Mid EXAMPLE URL: http://api.movieclips.com/v2/people/editor/0kft/videos?id_type=person-freebase-mid Description: The Freebase supplied guid of the person (in this case an editor) you want videos of. ID value must be url encoded. Please note that you cannot include the namespace identifier "/m/" in your request. If you include this you will generate a 404 response.
person-amg-id	REF URL: http://developer.rovicorp.com EXAMPLE URL: http://api.movieclips.com/v2/people/editor/P%2B%2B%2B%2B98309/videos?id_type=person-amg-id Description: The Rovi/AMG supplied id of the person (in this case an editor) you want videos of. ID value must be url encoded.
person-imdb-id	REF URL: http://imdb.com EXAMPLE URL: http://api.movieclips.com/v2/people/editor/nm0000041/videos?id_type=person-imdb-id Description: The IMDB supplied id of the person (in this case an editor) you want videos of. ID value must be url encoded.