Announcing the GDELT Thematic Word Cloud Dashboard API

 December 5, 2015

We're tremendously excited to announce the latest in our rapidly growing suite of GDELT API's: the GDELT Thematic Wordcloud Dashboard API. This new API service, created through the support of the PeaceTech Lab, is a live-updated embeddable word cloud of the top overall and top trending topics mentioned in coverage about a given country or administrative division, that you can drop into any website as a live browser-based visualization via an iframe or download and process yourself as a CSV file.

Updated every 15 minutes, the visualization tallies up all of the themes mentioned in coverage mentioning a given country over the last 2 hours and compiles a ranking of the top most-mentioned themes. It then compares those themes against the top themes for the preceding 2 hours to compile a list of the top "trending" topics that have increased the most. This allows you to display either the major topics defining a country's coverage or the topics that are rapidly rising to the top, capturing the constant ebb-and-flow of coverage over the course of a day and in reaction to major events.

You can also switch between all topics, functional actors (roles like "child," "woman," "burglar," "president" and so on), or a mixture of the two. This allows you to create word clouds that filter to the kinds of roles being mentioned with respect to a country, the topics and themes defining it, or the combined narrative environment.

You can see an example of the embeddable word cloud below, showing the top trending themes for France over the last two hours compared with the previous two hours.

You can embed this timeline in your own website using a simple iframe via the HTML code below:

<iframe src="https://api.gdeltproject.org/api/v1/dash_thematicwordcloud/dash_thematicwordcloud?LOC=FR&OUTPUT=viz&VAR=trendall" height="500" scrolling="no" width=500></iframe>

We'd like to thank the PeaceTech Lab for making this API possible and Google Ideas for their support of the GDELT Project.

OPTIONS

Below are all of the options that can be passed to the API.  Add them to the root API URL of "https://api.gdeltproject.org/api/v1/dash_thematicwordcloud/dash_thematicwordcloud".

  • LOC. This is the two-digit country code or four-digit ADM1 code for the location you wish to display data for.  GDELT uses the adapted FIPS codes from GNS, you can use our quick lookup files for country codes and ADM1 codes.  For example, to display data for Israel, you would use "LOC=IS". Note that for ADM1 codes, places with non-Latin characters may be missing characters due to the ASCII transcription we are presently using to ensure uniform compatibility with several libraries we are using for the API, but this will be upgraded shortly.
  • VAR. This defines which variable should be displayed.  The following options are currently supported:
    • VAR=trendfncact.  This displays the functional actors that are trending upwards in the last 2 hours compared with the preceding 2 hours.
    • VAR=trendnofncact.  This displays the top topics trending upwards in the last 2 hours compared with the preceding 2 hours.
    • VAR=trendall.  This displays a combined list of the top functional actors and topics trending upwards in the last 2 hours compared with the preceding 2 hours.
    • VAR=topfncact.  This displays the top functional actors mentioned most often in the last 2 hours.
    • VAR=topnofncact.  This displays the top topics mentioned most often in the last 2 hours.
    • VAR=topall.  This displays a combined list of the top functional actors and topics mentioned most often in the last 2 hours.
  • OUTPUT. This defines what kind of output should be produced.  The following options are currently supported:
    • OUTPUT=viz.  This produces an embeddable interactive JavaScript visualization that can be embedded into any website via a simple iframe as seen in the example above.  The image is rasterized into a PNG image to allow right-click downloading as a static image. NOTE that every time you refresh your browser window the visualization will change to a different layout due to the use of randomization in the layout algorithm.
    • OUTPUT=csv.  This produces a simple CSV output file that can be imported into any standard statistics package or parsed to create your own customized visualizations using a JavaScript toolkit like D3.

EXAMPLES