EVENT Heatmap Visualizer

EVENT Heatmap Visualizer

Dataset: GDELT Event Database

Description: Creates an interactive heatmap that displays in a browser window, along with a CSV file for importing into GIS software.

Components: PERL, heatmap.js, Google BigQuery, Google Maps

Acknowledgements: Makes use of the heatmap.js library and Google BigQuery.

Example: Heatmapping Hotspots.

The EVENT Heatmap Visualizer allows you to rapidly construct geographic heatmaps from the GDELT Event Database to understand spatial patterns in your search, and creates an interactive browser-based heatmap display and Latitude/Longitude .CSV file for more sophisticated analysis and visualization using GIS software. All events matching your search criteria are compiled and a list constructed of the city, landmark, and administrative division (roughly equivalent to a US state) location where each took place, which is then compiled to make a master histogram by latitude/longitude of the top locations associated with your search. This is then output in a live browser-based heatmap visualization and a .CSV file that you can readily import into GIS software for more sophisticated visualization and spatial analysis.

No programming or technical skills are required to use this visualization - you simply specify a set of criteria for the event type and actors involved, along with an optional date range, and the system will automatically search the entire GDELT Event Database for all matching entries and compile the final timeline. Your results will be emailed to you when complete, usually within 10 minutes, depending on server load and the time it takes to perform the necessary calculations. Selecting "Nigeria" as the "Event Location", "Material Conflict" as the "Event Quad Class", and "Civilian" as the "Recipient/Victim (Actor2) Type" will generate a heatmap of attacks and other conflict against civilians in Nigeria.

Your Email Address

Creating these results can take several minutes depending on server demand - please provide the email address that the results should be sent to.

Email Address

Date Range

Limit the time period of analysis. The earliest allowable date for event data is currently January 1, 1979 and the latest date allowed is the current day.

Start Date
End Date

Search Criteria - Actors

Select the specific actors involved in the event. The CAMEO taxonomy used by GDELT codifies an "event" as an action performed by one entity (Actor1) onto another (Actor2). GDELT codifies an array of 58 fields of information about each event. Using the form below you can restrict your search to just those events initiated by a specific country and/or type against another country and/or type. For example, to select all attacks on civilians in Nigeria, you would specify "Civilians" using the "Actor2 Type" dropdown below, "Nigeria" using the "Event Location" dropdown below, and then violence-related event types using the next section. To select all protests in Nigeria, you would leave the Actor section below blank, and select protest-related event types from the following section and "Nigeria" as the "Event Location."

Initiator (Actor1) Country:

Initiator (Actor1) Type:

Recipient/Victim (Actor2) Country:

Recipient/Victim (Actor2) Type:

Search Criteria - Event

Select the specific type and/or location of events you are interested in. The full CAMEO taxonomy defines over 300 specific categories of events, but to simplify things, the search interface below lets you search only for the 20 root categories under which those other event types fall, or you can select by "Quad Class", which groups the 20 root categories into 4 "super categories".

Event Code:
Event Quad Class:

Event Location:

Location Weighting

How should the "weight" of each location be calculated?

  • Number Events Each location is weighted by the total number of unique events found at that location, irrespective of how much news coverage each event received. This is useful to look strictly at the overall distribution of events, where all events are considered equal. Using this weighting, an event that is covered by 10,000 different news reports across the world will count the same as one that received just a single news report. This yields the best overall picture of where things are happening, but not necessarily where the "most important" ones are happening.
  • Number Articles Each location is weighted by the total number of news articles covering events found at that location. Using this weighting, an event that is covered by 10,000 different news reports across the world will count as 10,000 times more important as one that received just a single news report. This option uses the volume of media coverage of each event as a proxy for its perceived "importance" and thus offers the best overall picture of where the "most important" events are taking place (as measured by media coverage).


The following output files will be generated:

  • Interactive Heatmap Visualization Generates a ready-to-go heatmap visualization using the heatmap.js library that displays inside of your browser overlaid onto Google Maps. A horizontal slider in the upper-left of the visualization allows you to interactively adjust the upper cutpoint threshold of the heatmap to dynamically "slice" through the data.
  • .CSV File This outputs a .CSV file listing the unique latitude/longitude pairs found across all matching event records and the number of matching event records or articles for each. This can be imported into GIS software for more sophisticated visualization or analysis.