MOVIECLIPS API 0.2.2 documentation
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:
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
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 | Description: This feed contains videos that were desginated “Clip of the Day”.
|
| Recently Added | recently-added-videos | Description: This feed contains videos that were recently added to our library.
|
| Now In Theaters | in-theaters | Description: This feed contains videos from movies that are now in theaters.
|
| Opening this Week | opening-this-week | Description: This feed contains videos from movies that are opening this week.
|
| New on DVD | new-on-dvd | Description: This feed contains videos from movies that are new on dvd.
|
| Coming Soon | coming-soon | Description: This feed contains videos from movies that are opening soon.
|
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.
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.
| 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 | Description: Use this key to filter within actor names.
|
| director | Description: Use this key to filter within director names.
|
| producer | Description: Use this key to filter within producer names.
|
| role-name | Description: Use this key to filter within role names(e.g. batman).
|
| character-type | Description: Use this key to filter within character types.
|
| action | Description: Use this key to filter within actions.
|
| editors-choice | Description: Use this key to filter within editor’s choice.
|
| primary-genre | Description: Use this key to filter within primary genres.
|
| secondary-genre | Description: Use this key to filter within secondary genres.
|
| primary-occasion | Description: Use this key to filter within primary occasions.
|
| secondary-occasion | Description: Use this key to filter within secondary occasions.
|
| prop | Description: Use this key to filter within props.
|
| setting | Description: Use this key to filter within settings.
|
| studio | Description: Use this key to filter within studios.
|
| theme | Description: Use this key to filter within themes.
|
| mood | Description: Use this key to filter within moods.
|
| year | 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
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
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
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
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
Description: The IMDB supplied id of the movie you want videos of. ID value must be url encoded.
|
| 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
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
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
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
Description: The IMDB supplied id of the person (in this case an editor) you want videos of. ID value must be url encoded.
|