The bulk of our data falls within one of two categories:
videos. Both are further divided into types. Containers can be broken down into:
artists. Videos as:
clips. There's no strict relationship between a container and its videos. However, as a general rule, a
film will contain a single
series will container multiple
news will container multiple
news_clips and an
music_videos. All containers might container zero or more
clips. Again, none of this is strict. In addition to a
film could also contain a
Containers and videos share a number of common fields. One of the main differences is that a container will typically have one or more child elements of a video type, while a video will always have a single containing type.
The similarities between container and video is evident in the api. The parameters that you can pass to the
containers endpoint are pretty much the same as those you can pass to the
videos endpoint. Furthermore, the
movies endpoint is nothing more than the
videos endpoint with an additional
Most endpoints which return multiple results support the same three paging parameters. This is true not only of videos and containers, but also other items, such as
contributions. The three parameters are
per_page are used to navigate from page to page.
page=1&per_page=10 will return the first ten results, while
page=2&per_page=20 will return results 20-39. The maximum
per_page is 25.
By default, paging information will not be returned with the response. Instead, a
more field will be returned to indicate whether or not at least 1 additional result exists. Frankly, we chose this default because it performs better (both for us, and for you). Nevertheless, it is suitable for implementing infinite scrolling, short lists (like the top 5 most viewed videos), or even for simple next/prev paging.
with_paging=true to a query, complete paging information will be included. In addition to navigation links, a
count field will be included to indicate the total number of matched results.
In either case, the actual results are in the
response field. This should make it possible to utilize either paging strategy without requiring different implementations.
Like paging, multi-result endpoints also take three common sorting parameters. The one you're most likely to use is the
sort parameter which indicates the field to sort on. Different endpoints accept different
sort values. For containers and videos, acceptable values are:
views: most viewed (over all time)
views_recent: most reviewed (past X days - currently 7)
trending: most popular right now
created_at: date created
number: relevant for
newest_video: relevant to container types only
contributions though, can be sorted by
Some sort fields accept a
sort_value. For example,
trending all accept an ISO 3166 country code, which will sort by views/trending for that specific country. By default, the user's country is used.
desc can be specified. Note that, in most cases, this should not be specified as each sort field already has a logical direction associated with it. This is particularly true for
created_at as these actually represent the top X viewed/trending/created. In other words, reversing the list won't return the absolute least viewed/popular, but rather the least viewed/popular from a subset of the most viewed/popular.