GDELT 2.0 Television API Now Supports Weekly/Monthly/Yearly Aggregations

For many searches, hourly and daily time resolutions are more than enough to understand precisely how coverage of a given topic has changed over time when using the  GDELT 2.0 TV API. However, for search terms that yield either a lot of coverage or very little coverage or for which coverage is sporadic, reporting the percentage of matching airtime at a daily resolution can make it difficult to understand longitudinal patterns.

For example, charting daily coverage of "("climate change" OR "global warming")" yields a graph that does not immediately appear to show any major patterns. Switch to yearly resolution, on the other hand and a pattern immediately becomes clear, showing coverage peaking in 2009, declining sharply, resuming slightly and then declining again.

As before, daily resolution can be selected for any search and hourly resolution is available for all timespans 7 days or shorter. For timespans shorter than 3 years, daily resolution will remain the default, while for longer timespans all displays will now default to monthly resolution. You can override these defaults using the new "dateres=" parameter and setting it to either "hour" (available only for <7 day timespans), "day," "week," "month" or "year."

NOTE: We've made an important change to how the TV API handles dates. In the past when setting the start and end date/times, your selections were used as-is to the precision of one second. This created problems in that users would often set the start/stop times based on external inputs that would fall short of 00:00:00 or 23:59:59, meaning their queries would report fewer than a full day's worth of clips, prompting questions about why they weren't seeing all clips for the day. To address this, the TV API now automatically rounds all start and stop times to the start and stop of the current aggregation level. At hourly aggregation, the start and stop times are rounded to the beginning of the start hour and the end of the ending hour. For daily resolution they are rounded to midnight of the starting day and 23:59:59, inclusive, of the ending day. For weekly, monthly and yearly aggregations, the start and stop dates are similarly rounded to the start/end of the week, month and year. Note that this applies to ALL displays, including StationChart, WordCloud, ClipGallery, etc. Please keep these new rules in mind when interpreting results.

We hope these new aggregation levels will make it much easier to spot complex temporal patterns in your searches.