Viki Platform

Overview

The bulk of our data falls within one of two categories: containers and videos. Both are further divided into types. Containers can be broken down into: films, series, news and artists. Videos as: movies, episodes, news_clips, music_videos and clips. There's no strict relationship between a container and its videos. However, as a general rule, a film will contain a single movie, a series will container multiple episodes, a news will container multiple news_clips and an artist mutiple music_videos. All containers might container zero or more clips. Again, none of this is strict. In addition to a movie, a film could also contain a music_video.

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 type=movies parameter.

Paging

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 page, per_page and with_paging.

page and 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.

By adding 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.

Sorting

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:

Something like contributions though, can be sorted by segment or subtitle counts.

Some sort fields accept a sort_value. For example, views, views_recent and 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.

Finally, a direction of asc or 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 view, views_recent, trending and 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.