GdeltNodeEditor Documentation

Purpose

The GdeltNodeEditor is a component within the Vantage analytics and data platform that specializes in interfacing with the GDELT (Global Database of Events, Language, and Tone) datasets. It is designed to facilitate the creation and customization of queries for event search and trend analysis, enabling users to extract insights from global news data based on various parameters, such as time span, filtering options, sorting mechanisms, and themes.

Settings

1. Search Query

• Input Type: String
• Description: This setting allows the user to input a search query to filter events from the GDELT dataset. The input supports boolean search logic, where quotes can be used for exact phrases, and "OR" can be utilized between multiple query terms.
• Default Value: "" (empty string)

2. Time Span

• Input Type: Dropdown (Select)
• Description: Specifies the time frame for the events to be retrieved. The user selects from predefined intervals such as "15 minutes," "30 minutes," "1 hour," up to "3 months." A longer time span generally produces a larger dataset.
• Options: Includes values such as 15min, 30min, 1h, 6h, 12h, 1d, 3d, 7d, 14d, 1m, 3m.
• Default Value: 1d (1 day)

3. Max Results

• Input Type: Numeric (Range)
• Description: Controls the maximum number of records to return from the search. Increasing this limit allows for more results but may cause performance issues or slow responsiveness if set too high.
• Range: 10 to 250 (inclusive) in increments of 10.
• Default Value: 50

4. Sort By

• Input Type: Dropdown (Select)
• Description: Defines the criteria by which the results of the query will be sorted. Options include sorting by date (newest or oldest) or sentiment score (most positive or negative).
• Options: Includes values such as datedesc, dateasc, tonedesc, toneasc.
• Default Value: datedesc (Newest first)

5. Country

• Input Type: Dropdown (Select)
• Description: Allows the user to filter results based on the country of the news source. Selecting a specific country will limit the search results to only those originating from that country.
• Options: Includes countries like US, UK, CA, AU, IN, DE, etc.
• Default Value: "" (All countries)

6. Language

• Input Type: Dropdown (Select)
• Description: Enables filtering the events by the language of the source material. This setting ensures that only results in the desired language are returned.
• Options: Includes English, Spanish, French, German, Arabic, etc.
• Default Value: "" (All languages)

7. Theme

• Input Type: String
• Description: This input allows the user to specify various themes such as ‘TERROR’, ‘ECON_TRADE’, or ‘ELECTION’ that can be used for more refined searches within the dataset.
• Default Value: "" (empty string)

8. Domain

• Input Type: String
• Description: User can specify a domain to filter results based on the source's website. For instance, inputting nytimes.com will return results only from the New York Times.
• Default Value: "" (empty string)

9. Timeline Mode

• Input Type: Radio buttons
• Description: This allows the user to select how the timeline data will be represented, offering modes such as event volume, tone, country breakdown, and language breakdown.
• Options: Volume, Tone, By Country, By Language.
• Default Value: volume

10. Smoothing

• Input Type: Numeric (Range)
• Description: This setting determines the degree of smoothing applied to the timeline data, based on a moving average window. Setting it to 0 means no smoothing is applied.
• Range: 0 to 10 (inclusive) in steps of 1.
• Default Value: 0

How It Works

The GdeltNodeEditor allows users to build queries by populating the settings with their desired parameters. The editor interacts with GDELT's API to retrieve the results based on the defined criteria. Upon updating settings, the component handles the real-time updating of the query structure to reflect the user's choices, providing immediate visual feedback and easier debugging.

The component uses state management to maintain the current configuration, which subsequently triggers API calls to fetch data from the GDELT database, depending on the user-defined parameters.

Expected Data

GdeltNodeEditor expects data in the form of user input for each of its settings. The expected data types include strings for textual queries, ranges for numeric values like Max Results and Smoothing, and selections from predefined dropdown options. Users are responsible for inputting valid and meaningful configurations to ensure successful data retrieval.

Use Cases & Examples

Use Case 1: Political Event Analysis

A political analyst wants to study the frequency of articles regarding elections in the United States over the last month. They can configure the GdeltNodeEditor with a search query like "election", set the time span to "1 month", filter by country to "US", and sort by "datedesc" for the most recent articles.

Use Case 2: Health Trend Monitoring

Health organizations may wish to track articles related to pandemics and vaccination efforts. By setting the search query to "pandemic" or "vaccination", selecting a time span of "1 week", and choosing language as "English", they can analyze recent trends in public health media.

Example Configuration for Political Event Analysis

{
    "query": "election",
    "timespan": "1m",
    "maxRecords": 50,
    "sort": "datedesc",
    "country": "US",
    "language": "",
    "theme": "",
    "domain": "",
    "timelineMode": "volume",
    "smoothing": 0
}

In this configuration, the analyst aims to gather a concise set of the latest articles pertaining to elections in the US, allowing for timely insights into the political landscape.

AI Integrations & Billing Impact

While the GdeltNodeEditor itself does not directly integrate AI functionalities, the data collected through the component can be leveraged for advanced analytics tasks, potentially including AI-driven analysis for sentiment analysis, topic modeling, or predictive analytics.

In terms of billing, usage of the GdeltNodeEditor is based on the volume of data queried and processed. Higher settings for Max Results and more frequent requests may lead to increased resource consumption and subsequently affect billing based on the tier of service being utilized within the Vantage platform.