v2_tv_api | R Documentation |
Access data from GDELT Television V2 API
v2_tv_api(
terms = NULL,
use_exact_term = FALSE,
parse_data = TRUE,
return_message = TRUE,
networks = NULL,
stations = NULL,
contexts = NULL,
markets = NULL,
shows = NULL,
modes = "ClipGallery",
formats = "json",
use_combined_stations = FALSE,
data_normalization_parameter = "percent",
date_resolution = NULL,
include_last_24_hours = FALSE,
maximum_records = 3000,
sort_variable = "DateDesc",
timeline_smooth = NULL,
start_date = NULL,
end_date = NULL,
timespan = NULL,
timezone_adjust = NULL,
time_zoom = NULL
)
terms |
Vector of terms |
use_exact_term |
If 'TRUE' uses exact term |
parse_data |
If 'TRUE' parses data |
return_message |
If 'TRUE' returns a message |
networks |
Vector of networks |
stations |
Vector of stations |
contexts |
Vector of contexts |
markets |
Vector of markets |
shows |
Vector of shows |
modes |
|
formats |
This controls what file format the results are displayed in. Not all formats are available for all modes. To assist with website embedding, the CORS ACAO header for all output of the API is set to the wildcard "*", permitting universal embedding.
|
use_combined_stations |
If ‘TRUE' both timeline and station chart modes separate out each matching station’s data to make it possible to compare the relative attention paid to a given topic by each station. Sometimes, however, the interest is in overall media attention, rather than specific per-station differences in that coverage. Setting this parameter to "combined" will collapse all matching data into a single "Combined" synthetic station and make it much easier to understand macro-level patterns |
data_normalization_parameter |
Most media researchers are accustomed to working with raw result counts, such as the absolute number of 15 second clips that matched a given query. Such raw counts, while useful quick "sanity checks", are inappropriate for production analysis, especially looking over time or across stations. Raw clip counts reflect the absolute number of clips that matched a given query. However, one station may devote more of its airtime to commercials or non-news entertainment programming (which are largely excluded by the TV Explorer) and thus render such comparisons meaningless. Instead, by default the API normalizes timeline and station chart modes by dividing the number of matching clips in each time interval by the total number of all monitored clips from that station or set of stations over that time interval. For example, if searching for "trump" on CNN over the past 2 years in timeline mode, each day will be displayed as the percent of all 15 second clips monitored from CNN that day that contained the word "trump" somewhere in that 15 second interval. This transforms result counts into normalized density measurements that allow you to directly compare different periods of time or stations in a meaningful way. We strongly recommend that users use only normalized result counts (the default), but for cases where you need raw counts, you can set this parameter to.
|
date_resolution |
By default results are returned in hourly resolution (for <7 day timespans), daily resolution for <3 year timespans and monthly resolution otherwise. You can override these settings and manually set the time resolution to any of the following values. NOTE that this will automatically adjust the STARTDATETIME and ENDDATETIME parameters to their start/stop dates/times at the given date resolution.
|
include_last_24_hours |
If 'TRUE' includes the most recent 24 hours of data in the timeline. By default, the timeline will not display the most recent 24 hours, since those results are still being generated (it can take up to 2-12 hours for a show to be processed by the Internet Archive and ready for analysis), but you can include those if needed via the LAST24 option. |
maximum_records |
This option only applies to ClipGallery mode. By default 50 clips are displayed in HTML mode. In JSON, JSONP or CSV formats, up to 3,000 clips can be returned |
sort_variable |
By default results are sorted by relevance to your query. Sometimes you may wish to sort by date or tone instead. |
timeline_smooth |
This option is only available in timeline mode and performs moving window smoothing over the specified number of time steps, up to a maximum of 30. Timeline displays can sometimes capture too much of the chaotic noisy information environment that is the television landscape, resulting in jagged displays. Use this option to enable moving average smoothing up to 30 time steps to smooth the results to see the macro-level patterns. Note that since this is a moving window average, peaks will be shifted to the right, up to several days or weeks at the heaviest smoothing levels |
start_date |
Start date; The earliest available date is July 2, 2009. If you do not specify an ENDDATETIME, the API will search from STARTDATETIME through the present date/time |
end_date |
End Date; If you do not specify a STARTDATETIME, the API will search from July 2, 2009 through the specified ENDDATETIMEs |
timespan |
By default the TV API searches the entirety of the Internet Archive's Television News Archive's holdings, which extend back to July 2009 for some stations. You can narrow this range by using this option to specify the number of months, weeks, days or hours (minimum of 1 hour). The API then only searches airtime within the specified timespan backwards from the present time. If you would instead like to specify the precise start/end time of the search instead of an offset from the present time, you should use the STARTDATETIME/ENDDATETIME parameters
|
timezone_adjust |
By default STARTDATETIME, ENDDATETIME and all returned results are interpreted and reported in the UTC timezone. Use this parameter to adjust to any of the following major timezones: -12:00, -11:00, -10:00, -09:30, -09:00, -08:00, -07:00, -06:00, -05:00, -04:00, -03:30, -03:00, -02:30, -02:00, -01:00, +00:00, +01:00, +02:00, +03:00, +03:30, +04:00, +04:30, +05:00, +05:30, +05:45, +06:00, +06:30, +07:00, +08:00, +08:45, +09:00, +09:30, +10:00, +10:30, +11:00, +12:00, +12:45, +13:00, +13:45 or +14:00. Note that UTC offsets are treated as-is over the entire timespan, meaning that the offset is not adjusted to account for periods in which daylight savings is honored. |
time_zoom |
This option is only available for timeline modes in HTML format output and enables interactive zooming of the timeline using the browser-based visualization. Set to "yes" to enable and set to "no" or do not include the parameter, to disable. By default, the browser-based timeline display allows interactive examination and export of the timeline data, but does not allow the user to rezoom the display to a more narrow time span. If enabled, the user can click-drag horizontally in the graph to select a specific time period. If the visualization is being displayed directly by itself (it is the "parent" page), it will automatically refresh the page to display the revised time span. If the visualization is being embedded in another page via iframe, it will use postMessage to send the new timespan to the parent page with parameters "startdate" and "enddate" in the format needed by the STARTDATETIME and ENDDATETIME API parameters. The parent page can then use these parameters to rewrite the URLs of any API visualizations embedded in the page and reload each of them. This allows the creation of dashboard-like displays that contain multiple TV API visualizations where the user can zoom the timeline graph at the top and have all of the other displays automatically refresh to narrow their coverage to that revised time frame |
library(gdeltr2)
v2_tv_api(terms = c("Walz", "JD Vance"), formats = c("json"), modes = "TimelineVol")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.