/videos/views/list¶

Parameters¶

start_date (optional) : unsigned integer

UTC date starting from which videos views statistics should be returned. Date must be in Unix timestamp format. Default is the first day of the current month.

end_date (optional) : unsigned integer

UTC date until (and including) which videos views statistics should be returned. Date must be in Unix timestamp format. Default is today’s date.

list_by (optional) : string

Specifies videos views statistics listing type:

video

Videos views statistics listed by a video.

day

Videos views statistics listed by a day.

Default is video.

text (optional) : string

Case-insensitive search in the video key, title, author, description and tags fields. Only videos that contain search string in at least one of the search fields will be listed. Applicable only when list_by parameter set to video.

author (optional) : string

List only videos that contain specified search string in the author field. Search is case-insensitive. Applicable only when list_by parameter set to video.

order_by (optional) : string

Specifies parameters by which returned result should be ordered. Parameter sort order can be specified by appending :asc for an ascending sort order or :desc for a descending one to the parameter name. Default sort order is ascending and can be omitted. Multiple parameters should be separated by comma.

Result can be ordered by the following parameters: key, title, views, streams, downloads, pageviews and viewed. Default is views:asc.

Applicable only when list_by parameter set to video.

result_limit (optional): unsigned integer

Specifies maximum number of videos to return. Default is 50. Maximum result limit is 1000. Applicable only when list_by parameter set to video.

result_offset (optional): unsigned integer

Specifies how many videos should be skipped at the beginning of the result set. Default is 0.

aggregate (optional) : string

Specifies if returned videos daily views statistics should be aggregate.

True

Aggregate videos daily views for the specified date range.

False

Do not aggregate videos daily views.

Default is False.

group_days (optional) : string

Specifies if returned videos daily views statistics should be grouped by year and month.

True

Group daily videos views statistics by year and month.

False

Do not group daily videos views.

Default is False. Applicable only when list_by parameter set to day.

include_empty_days (optional) : string

Specifies if videos views statistics should include days for which there is no statistics available:

True

Daily views statistics will include empty days. Videos views for the empty days will be set to 0.

False

Daily views statistics will not include empty days.

Default is False. Applicable only when list_by parameter set to day.

statuses_filter (optional): string

List only videos with the specified statuses. Filter string can include the following statuses:

active

List only videos with status active.

deleted

List only videos with status deleted.

Each status in the filter string should be separated by comma. By default statuses filter is not applied.

Example response (list_by == video)¶

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <limit>50</limit>
  <offset>0</offset>
  <total>7</total>
  <videos total="7">
    <video key="yYul4DRz">
      <downloads>7</downloads>
      <pageviews>42</pageviews>
      <status>active</status>
      <streams>28</streams>
      <title>My cool video</title>
      <viewed>12345</viewed>
      <views>35</views>
    </video>
    ...
  </videos>
</response>

Response parameters¶

/response/status : string

Call execution status. Set to ok if call executed successfully.

/response/limit : unsigned integer

Maximum number of videos that should be return. As specified in the result_limit request parameter.

/response/offset : unsigned integer

Number of videos that should be skipped at the beginning of the result set. As specified in the result_offset request parameter.

/response/total : unsigned integer

Total number of videos.

//videos/@total : unsigned integer

Total number of returned videos.

//video/@key : string

Video key.

//video/streams : unsigned integer

Number of times the video was streamed in the specified date range.

//video/downloads : unsigned integer

Number of times the video was downloaded in the specified date range.

//video/views : unsigned integer

Number of times the video was streamed and downloaded (//video/streams + //video/downloads) in the specified date range.

//video/pageviews : unsigned integer

Number of times the video was embedded on a page in the specified date range.

//video/viewed : unsigned integer

Number of seconds the video was viewed in the specified date range.

//video/title : string

Title of the video.

//video/status : string

Video status:

active

Video is active.

deleted

Video has been deleted.

Example response (list_by == day AND group_days == False)¶

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <days total="27">
    <day date="2009-10-01" timestamp="1254355200">
      <downloads>49</downloads>
      <pageviews>294</pageviews>
      <streams>196</streams>
      <viewed>86415</viewed>
      <views>245</views>
    </day>
    ...
  </days>
</response>

Response parameters¶

/response/status : string

Call execution status. Set to ok if call executed successfully.

//days/@total : unsigned integer

Total number of returned days.

//day/@date : string

UTC date of the day in YYYY-MM-DD format.

//day/@timestamp : unsigned integer

UTC date of the day in Unix timestamp format.

//day/streams : unsigned integer

Number of times all videos were streamed this day.

//day/downloads : unsigned integer

Number of times all videos were downloaded this day.

//day/views : unsigned integer

Number of times all videos were streamed and downloaded (//day/streams + //day/downloads) this day.

//day/pageviews : unsigned integer

Number of times all videos were embedded on a page this day.

//day/viewed : unsigned integer

Number of seconds all videos were viewed this day.

Example response (list_by == day AND group_days == True)¶

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <years total="1">
    <year number="2009">
      <months total="1">
        <month number="10">
          <days total="27">
            <day number="1" timestamp="1254355200">
              <downloads>49</downloads>
              <pageviews>294</pageviews>
              <streams>196</streams>
              <viewed>86415</viewed>
              <views>245</views>
            </day>
            ...
          </days>
        </month>
      </months>
    </year>
  </years>
</response>

Response parameters¶

/response/status : string

Call execution status. Set to ok if call executed successfully.

//years/@total : unsigned integer

Total number of returned years.

//year/@number : unsigned integer

Number of the year.

//month/@total : unsigned integer

Total number of returned month for the year.

//month/@number : unsigned integer

Number of the month in a year (1..12).

//days/@total : unsigned integer

Total number of returned days.

//day/@number : unsigned integer

Number of the day in a month (1..31).

//day/@date : string

UTC date of the day in YYYY-MM-DD format.

//day/@timestamp : unsigned integer

UTC date of the day in Unix timestamp format.

//day/streams : unsigned integer

Number of times all videos were streamed this day.

//day/downloads : unsigned integer

Number of times all videos were downloaded this day.

//day/views : unsigned integer

Number of times all videos were streamed and downloaded (//day/streams + //day/downloads) this day.

//day/pageviews : unsigned integer

Number of times all videos were embedded on a page this day.

//day/viewed : unsigned integer

Number of seconds all videos were viewed this day.

Example response (list_by == day AND aggregate == True)¶

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <downloads>1813</downloads>
  <pageviews>10878</pageviews>
  <streams>7252</streams>
  <viewed>3197355</viewed>
  <views>9065</views>
</response>

Response parameters¶

/response/status : string

Call execution status. Set to ok if call executed successfully.

/response/streams : unsigned integer

Number of times all videos were streamed in the specified date range.

/response/downloads : unsigned integer

Number of times all videos were downloaded in the specified date range.

/response/views : unsigned integer

Number of times all videos were streamed and downloaded (/response/streams + /response/downloads) in the specified date range.

/response/pageviews : unsigned integer

Number of times all videos were embedded on a page in the specified date range.

/response/viewed : unsigned integer

Number of seconds all videos were viewed in the specified date range.