The GDELT Project

GDELT GEO 2.0 API Debuts!

We are immensely excited today to announce the debut of the first of the GDELT 2.0 APIs: the GDELT GEO 2.0 API! Two years in the making, this API takes everything we've learned from our original GeoJSON API, the lessons we've learned from more than a decade mapping the geography of text, and all of your feedback and requests and woven them into what we hope is a transformative new way of accessing the geography of worldwide news coverage.

Perhaps most importantly, the new API now allows you to create maps of any arbitrary keyword or phrase, rather than being limited to just the GKG topical themes of the previous GeoJSON API. Now you can enter any English keyword and instantly receive back a map of every location mentioned within a sentence or two of your keyword across everything GDELT has monitored in all 65 live machine translated languages over the last 7 days, updated every 15 minutes. Now no matter what word or phrase you're interested in, you can map it and even combine multiple terms into basic boolean OR statements.

Instant Interactive Maps

We heard you loud and clear that the previous system, with its GeoJSON-only output, was too difficult for non-technical users to get started with. Towards this end the new API generates instant intuitive interactive maps at landmark, first order administrative and country levels and these maps can be embedded directly in your own website, updating every 15 minutes. No need to understand what GeoJSON is or how to build a map, just enter your keywords and get back an instant map that you can use as-is. At the same time, the API generates fully compliant GeoJSON files that you can bring right into online mapping platforms like Carto to generate rich geographic experiences where you can fully customize the map's appearance and integrate additional datasets and map layers to tell complex cartographic stories. When generating country and ADM1-level maps, the API even outputs the complete polygonal geometry of each country/ADM1 as part of the GeoJSON file, meaning you can import it instantly into Carto without any further work.

Search The World's News Imagery

It is also the first API to provide programmatic friendly access to the GDELT Visual Knowledge Graph (VGKG), allowing you to leverage the results of some of the world's most advanced deep learning algorithms cataloging the world's news imagery each day to create realtime-updating maps of the visual narratives of global news content. Map global protests or natural disasters like flooding based not on textual mentions of a flood, but actual ground truthed imagery emerging from the scene. Map happy joyful protests where everyone is smiling and cheerful or map angry or violent protests, all based on facial expressions. Search any snippet of text found the images (from foreground labels to a protest sign in the background) in more than 80 languages, any metadata found in the EXIF and other fields in the image file, the textual caption of the image from the page it was found on and expand to include all of the captions used for the image everywhere it appeared on the web that Google Images could find.

As of September 3, 2017 we are now using a new generation architecture for georeferencing images, using a combination of visual geocoding and caption processing, rather than the old textual geocoding linking, so mapping images by the locations they depict should now be highly accurate.

Massive Complexity

Given the immense complexity of monitoring worldwide news media in nearly every country of the world across more than 100 languages, visually identifying and extracting the actual article text from the rest of the page, machine translating the incredible complexity and nuance of more than 65 languages in realtime and geocoding and disambiguating more than 9 million places on earth down to the level of a remote isolated hilltop, together with deep learning analysis of imagery reflecting the entirety of global human experience, you will almost always see at least some level of error in the results this API provides. This can range from one city being confused for another of the same name and context to a city name being mistranslated to an unrelated temporary breaking news inset at a different location being incorrectly inserted into the middle of an article. With anything this massive, you will always find some level of error when you dive deeply enough into the results, but overall the maps should accurately reflect the broad contours of the geography of your search.

 

QUICK START EXAMPLES

Here are some really simple examples to get you started using the API!

FULL DOCUMENTATION

The GDELT GEO 2.0 API is accessed via a simple URL with the following parameters.