GDELT Integration for Vantage

Overview

The GDELT (Global Database of Events, Language, and Tone) integration for Vantage provides a robust interface for interacting with the GDELT 2.0 API. This powerful resource contains a vast dataset of global news articles and events, enabling users to perform in-depth analyses and extract meaningful insights. The integration consists of several functions for querying articles, generating timelines, obtaining geographic event data, and visual content.

Purpose

The primary purpose of the GDELT integration is to facilitate easy access to the GDELT API without the need for user authentication. This integration allows developers and analysts to pull relevant news and event data programmatically, opening avenues for research, data analysis, real-time monitoring, and trend detection.

Settings

The following settings are configurable in the GDELT integration:

Query Parameters

1. query

   • Type: String
   • Description: This is the primary search term or keyword for filtering articles. Entering a specific phrase will refine the search results accordingly.
   • Default Value: undefined (no default)

2. country

   • Type: String
   • Description: This parameter allows the user to filter results based on the source country of the articles. It should be provided using ISO country codes (e.g., 'USA', 'GBR').
   • Default Value: undefined (no default)

3. theme

   • Type: String
   • Description: Users can specify a theme or topic of interest. Providing a theme will restrict the results to articles identified under that particular category.
   • Default Value: undefined (no default)

4. domain

   • Type: String
   • Description: This setting filters results based on specific domains. Users can specify news websites or online sources.
   • Default Value: undefined (no default)

5. language

   • Type: String
   • Description: This parameter allows users to filter articles by the source language. Language codes should be provided (e.g., 'en' for English).
   • Default Value: undefined (no default)

6. toneFilter

   • Type: String
   • Description: Users can specify a range of tone values to filter articles based on sentiment (e.g., '0,5' for neutral articles). This uses tone scores from the GDELT analysis.
   • Default Value: undefined (no default)

7. maxRecords

   • Type: Numeric
   • Description: This setting limits the maximum number of records returned by a query. The integration ensures that the maximum does not exceed 250.
   • Default Value: 50

8. timespan

   • Type: String
   • Description: This parameter determines the time range for the articles being queried. Format must be consistent with GDELT specifications (e.g., '1d' for one day, '7d' for seven days).
   • Default Value: 1d

9. sort

   • Type: String
   • Description: Users can specify the sort order for the results. Options include 'datedesc' (default) for sorting by date in descending order, or other GDELT sort options.
   • Default Value: datedesc

10. timelineMode

• Type: String
• Description: This setting specifies the type of data to retrieve for timeline analyses, including volume, tone, country breakdowns, or language distribution.
• Default Value: volume

11. smoothing

• Type: Boolean
• Description: This parameter applies smoothing algorithms to the timeline data. When set to true, it may produce a more visually appealing representation of trends over time.
• Default Value: undefined (no default)

How It Works

The GDELT integration works by sending HTTP requests to the GDELT API endpoints based on user-defined configuration parameters. The integration includes:

1. Building a Query URL: The buildUrl function constructs the request URL based on user-provided parameters.

2. Fetching Data: The gdeltFetch function handles all API calls, implementing retry logic for handling rate limits and network errors. It ensures the requests return JSON-formatted responses and deals with various potential issues like request timeouts or empty responses.

3. Querying Articles: The searchArticles function allows users to retrieve articles based on configurable parameters, relying on the constructed URL to fetch results.

4. Getting Timelines and Tone Charts: The integration provides advanced functionalities to analyze data over time and visualize sentiment trends using the getTimeline and getToneChart functions.

5. Geographic Data Retrieval: With getGeo, users can obtain GeoJSON data that includes geographical metadata for events tied to the articles.

Data Expectations

The GDELT integration expects certain types of data inputs based on the defined settings. This includes:

• Search queries which must be properly formatted strings.
• Language and country filters which need valid ISO codes.
• Tone filters that must be represented as numeric ranges.
• Time spans formatted in accepted GDELT formats.

Use Cases & Examples

Use Case 1: Market Analysis

A market analyst could leverage the GDELT integration to monitor media coverage of emerging markets through targeted articles over a selected timeframe. By analyzing sentiment trends, the analyst can gauge investor interests and concerns.

Use Case 2: Social Event Tracking

A non-profit organization can use GDELT data to track social movements and their media portrayal across various countries, identifying trends in public sentiment and areas that require engagement.

Example Configuration

For a case where the goal is to monitor global sentiment on climate change over the past week, the configuration for the GDELT integration could look like this:

{
  "query": "climate change",
  "country": "USA",
  "theme": "environment",
  "maxRecords": 100,
  "timespan": "7d",
  "sort": "datedesc",
  "toneFilter": "0,5"
}

In this example, the analyst would receive the latest 100 articles regarding climate change from the USA within the past week, focusing on articles that have a neutral to mildly positive tone. The results can inform policies or campaigns aimed at increasing environmental awareness.