eventSearch Documentation

Purpose

The eventSearch logic is designed to interface with the GDELT (Global Database of Events, Language, and Tone) API. It enables users to search for global events and articles based on different parameters such as keywords, country, themes, domains, languages, and tones. This functionality is critical for applications that require the aggregation and analysis of real-time news and events across the globe.

Settings

The eventSearch component includes several settings that can be customized to fine-tune the behavior of the event search. Below is a detailed breakdown of each setting.

1. query

• Input Type: String
• Description: This parameter holds the search query for articles or events. It determines what keywords will be used for the search.
• Default Value: '' (an empty string)
• Impact: If this parameter is not provided, the search will not execute, and an error (No search query provided) will be returned. The search results are directly influenced by the content of the query.

2. timespan

• Input Type: String
• Description: This setting specifies the time range for the search results. It can accept values such as '1d' for one day, '7d' for one week, and other formats as supported by the GDELT API.
• Default Value: '1d'
• Impact: Adjusting this setting will modify the timeframe from which the articles are retrieved. A longer timespan may yield more results but can also dilute the relevance compared to a shorter, more recent timeframe.

3. maxRecords

• Input Type: Numeric
• Description: This parameter limits the maximum number of articles returned in the search results.
• Default Value: 50
• Impact: If set to a lower value, the number of articles retrieved will decrease, which can be useful when only a snapshot is needed or when there are limitations on displaying results.

4. sort

• Input Type: String
• Description: This setting determines the order in which the search results are returned. Accepted values might include 'datedesc' for descending order by date and possibly others depending on API specifications.
• Default Value: 'datedesc'
• Impact: Changing the sort order will directly affect how the results are displayed, impacting user experience. For example, if set to an ascending order, older articles will appear first.

5. country

• Input Type: String
• Description: This parameter allows filtering articles based on country. It usually accepts ISO country codes (e.g., 'US' for the United States).
• Default Value: '' (an empty string)
• Impact: Providing a value here will limit the results to articles originating from the specified country, allowing for focused searches.

6. theme

• Input Type: String
• Description: This setting allows searches to be refined based on thematic categories. It enhances the targeting of the search results.
• Default Value: '' (an empty string)
• Impact: If specified, only articles associated with the given theme will be retrieved, narrowing the scope of the search.

7. domain

• Input Type: String
• Description: This parameter enables filtering articles by domains or specific websites.
• Default Value: '' (an empty string)
• Impact: By setting this parameter, users can focus on generating results from preferred sources, such as specific news websites.

8. language

• Input Type: String
• Description: This setting allows the user to filter articles based on the language in which they are written.
• Default Value: '' (an empty string)
• Impact: Specifying a language code (e.g., 'en' for English) ensures that only articles in the designated language are returned.

9. toneFilter

• Input Type: String
• Description: This parameter can filter articles based on the emotional tone or sentiment identified within the text. It may accept specific tone descriptors supported by the GDELT API.
• Default Value: '' (an empty string)
• Impact: By applying a tone filter, users can retrieve articles that match specific emotional characteristics (e.g., positive, negative), enhancing query relevance.

How It Works

The eventSearch function asynchronously executes a search for articles using the configured parameters. Upon receiving the inputs and config, the function:

1. Constructs a search configuration object (searchConfig) that consolidates the parameters for the search.
2. Validates that the query field is not empty; if it is, an error message is returned.
3. Calls the searchArticles method from the GDELT integration with the constructed searchConfig.
4. Processes the results:
   • If articles are found, they are returned.
   • If no results are found, a default object is returned indicating no results.
   • In case of an error during the API call, the error message is returned.

AI Integrations

The eventSearch component does not incorporate any direct AI integrations. However, by leveraging the GDELT API, it indirectly utilizes AI to analyze and categorize news coverage and global events, offering insights into trends, sentiment, and thematic occurrences.

Billing Impact

Utilizing the eventSearch functionality may incur costs depending on the API usage limits set by GDELT, which typically depends on the number of requests made and the volume of data retrieved. It is advisable to review the GDELT API usage policy to understand potential impacts on billing.

Use Cases & Examples

Use Case 1: International News Monitoring

A global corporation wants to monitor international news for events affecting supply chain logistics. Using eventSearch, they can search for articles mentioning specific keywords related to logistics and filter them by country.

Use Case 2: Social Media Sentiment Analysis

A marketing team wishes to analyze the sentiment of articles published online regarding their brand. By setting a specific toneFilter, they can retrieve articles reflecting positive or negative sentiments of brand mentions.

Detailed Example Configuration

Scenario: A business needs to monitor logistics-related articles in the United States over the past week, with a maximum of 30 articles returned, sorted by the date.

Sample Configuration Data:

{
    "query": "logistics transport supply chain",
    "timespan": "7d",
    "maxRecords": 30,
    "sort": "datedesc",
    "country": "US",
    "theme": "",
    "domain": "reuters.com",
    "language": "en",
    "toneFilter": "positive"
}

Using this configuration, the eventSearch component would return the most recent 30 articles written in English about logistics, focusing particularly on positive sentiment within the United States.