Question

I have a Ruby script which downloads YouTube Insight reports for specific videos within specific date ranges. It authorizes with ClientLogin, retrieves <entry> XML data for a video, and extracts from that data a URL which points to a CSV report:

http://insight.youtube.com/video-analytics/csvreports
  ?query={VIDEO_ID}
  &type=v
  &starttime=1315353600000
  &endtime=1317772800000
  &user_starttime=1317168000000
  &user_endtime=1317772800000
  &region=world
  &token={API_TOKEN}
  &hl=en_US

The above URL works. However, I want a report for a specific date range, not the default range provided.

An Insight report query’s requested date range is set in the user_starttime and user_endtime params. (In the above default case, it’s 2011-09-27 through 2011-10-04.) The YouTube API docs say that you can specify your own date range (covering a span of up to 28 days) by substituting timestamps (in milliseconds) that represent the dates you want.

So, why does the following query 404?

http://insight.youtube.com/video-analytics/csvreports
  ?query={VIDEO_ID}
  &type=v
  &starttime=1315353600000
  &endtime=1317772800000
  &user_starttime=1307937600000
  &user_endtime=1308110400000
  &region=world
  &token={API_TOKEN}
  &hl=en_US

The date range looks OK:

ruby > Time.at 1307937600
=> 2011-06-13 00:00:00 -0400 
ruby > Time.at 1308110400
=> 2011-06-15 00:00:00 -0400 

The fact that the “default” URL works indicates that I must be doing something wrong with these date values, but I can’t figure out what. What am I overlooking?

Answer 1

UPDATE 2 — Nov. 4, 2011:

There has recently been a change to the YouTube Data API Protocol for Insight data, and the answer below is no longer accurate.

YouTube now permits date ranges of up to 31 days for a single Insight report query, and they now allow requests pertaining to dates going back to March 1, 2009. The docs now say:

You can adjust the date range for which a report contains data 
to a period of up to 31 days beginning no earlier than March 1, 2009. 

This is excellent news. (Leaving the below for posterity.)

---

I believe I’ve figured out why the above Insight report query with the custom date range is 404ing. I was able to retrieve a report with a custom date range like this:

http://insight.youtube.com/video-analytics/csvreports
?query={VIDEO_ID}
&type=v
&starttime=1315353600000
&endtime=1317772800000
&user_starttime=1315627200000
&user_endtime=1315972800000
&region=world
&token={API_TOKEN}
&hl=en_US

What’s the difference between this (good) URL and the previous (bad) URL in my question above? Well, my custom date range here, specified in the user_starttime and user_endtime parameters both fall within the range set by YouTube in the starttime and endtime params.

In other words, starttime and endtime seem to represent the outer bounds of any user-specified custom date range possible through these types of requests.

So, when the YouTube API docs say:

You can adjust the date range for which a report contains data to a period of up to 28 days

What they mean, I suppose, is:

• Your date range may not span more than 28 days … AND ALSO …
• Your date range may not fall outside of a date range going back 28 days from the most recent date on which reports are currently available, which we tell you through the starttime and endtime parameters.

UPDATE:

In this thread, a YouTube API Team member says:

You should consider the starttime value the absolute earliest supported start date and endtime the absolute latest supported end date. If you try to set user_starttime to something earlier than starttime then you’re going to ask for data that dates back more than 28 days, and that data isn’t available.

This exact text should be in the documentation.