Query GDELT V2 Full Text API

Source: R/gdelt_full_text_api.R

Queries GDELT's full text API for user specified terms, machine learned items, web domains and more. Users can return raw data or a Trelliscope of visual results. Data is a available in rolling three month periods.

ft_v2_api(
  terms = NA,
  quote_terms = F,
  domains = NA,
  images_face_tone = NA,
  images_num_faces = NA,
  images_ocr = NA,
  images_tag = NA,
  images_web_tag = NA,
  images_web_count = NA,
  source_countries = NA,
  source_languages = "English",
  gkg_themes = NA,
  tone = NA,
  tone_absolute_value = NA,
  use_or = FALSE,
  modes = "ArtList",
  timespans = c("24 hours"),
  dates = NA,
  maximum_records = 250,
  translate = NULL,
  timeline_smooth = 5,
  sort_by = "DateDesc",
  visualize_results = TRUE,
  sleep_time = 6,
  trelliscope_parameters = list(path = NULL, rows = 1, columns = 2, id_columns = NULL,
    group_columns = NULL),
  nest_data = FALSE,
  return_message = TRUE
)

Arguments

terms

a vector of terms

domains

a vector of webdomains

images_face_tone

vector of facial tone scores

images_num_faces

vector of face count

images_ocr

vector of words to search for OCR'd text

images_tag

vector of image tags from the image tag code book. use dictionary_ft_codebook(code_book = "imagetag")) for options

images_web_tag

vector of image tags from the image web tag code book. use dictionary_ft_codebook(code_book = "imageweb"))

images_web_count

numeric vector of number of times photo appeared

source_countries

character source countries #' see dictionary_ft_codebook(code_book = "countries") for options

source_languages

source languages

gkg_themes

global knowledge graph theme #' use dictionary_ft_codebook(code_book = "gkg")) for options

tone

numeric tone - default (NA)

tone_absolute_value

numeric tone absolute value (default NA)

use_or

if TRUE chains multiple items using and or statement else chained by and

modes

API search mode

  • ArtList - data frame of articles for specified terms/domains/webtags/imagewebtags and OCR'd text (default)

  • ImageCollage - data frame of images from for specified terms/domains/webtags/imagewebtags and OCR'd text

  • ImageCollageInfo - data frame of images from the article for specified terms/domains/webtags/imagewebtags and OCR'd text, includes information on age of the photo and number of uses

  • ImageCollageShare - data frame of images shared on social media from the article for specified terms/domains/webtags/imagewebtags and OCR'd text, includes information on age of the photo and number of uses

  • TimelineVol - Timeline of of article volume for specified terms/domains/webtags/imagewebtags and OCR'd text

  • TimelineVolInfo - Timeline of of article volume with article information for specified terms/domains/webtags/imagewebtags and OCR'd text

  • TimelineTone - Timeline of of article tone for specified terms/domains/webtags/imagewebtags and OCR'd text

  • TimelineLang - Timeline of of article language for specified terms/domains/webtags/imagewebtags and OCR'd text

  • TimelineSourceCountry - Timeline of of article sourcelanguage for specified terms/domains/webtags/imagewebtags and OCR'd text

  • ToneChart - histogram of binned counts by tone for specified terms/domains/webtags/imagewebtags and OCR'd text

  • WordCloudNative - word cloud of native text for specified specified terms/domains/webtags/imagewebtags and OCR'd text

  • WordCloudImageTags - word cloud of resolved imagetags for specified terms/domains/webtags/imagewebtags and OCR'd text

  • WordCloudImageWebTags - word cloud of resolved image web tags for specified terms/domains/webtags/imagewebtags and OCR'd text

timespans

character vector of the time frame - no more than 52 weeks - default is 24 hours acceptable periods include:

  • hours (default)

  • minutes

  • weeks

  • months

  • years

dates

vector of dates in YMD HMS format, separated by - you can use the generate_dates() function to generate a vector of default NULL

maximum_records

Number between 1 and 250

translate

if TRUE translates

timeline_smooth

if mode is a timeline

sort_by

sorting method

  • DateDesc - descending by date (default)

  • DateAsc - ascending by date

  • ToneDesc - descending tone

visualize_results

if TRUE returns a visualization

sleep_time
trelliscope_parameters

list of parameters to pass along to trelliscope

  • path: if not NULL the path to save the trelliscope

  • rows: rows for trelliscope

  • columns: columns for trelliscope

  • id_columns: initial columns

nest_data

if TRUE returns a nested tibble()

return_message

if TRUE returns a message

Value

a tibble or a form of visualization

Examples

terms <- c('"Brooklyn Nets"', '"Donovan Mitchell"', 'Blackston Real Estate', '"Tom Brady"')
web_sites <- c("realdeal.com", "netsdaily.com", "wsj.com", "archdaily.com", "alphr.com")
ft_v2_api(terms = terms, domains = web_sites, timespans = "28 Weeks")