gkgSearch Documentation

Overview

The gkgSearch component is designed to query articles from the GDELT Global Knowledge Graph (GKG) based on specified themes and search queries. It allows users to utilize categorized theme presets or enter custom themes, facilitating precise and informed searches within a defined timespan and various parameters.

Purpose

The primary purpose of the gkgSearch component is to retrieve relevant articles from the GDELT database that match specific keywords or theme criteria. This component can be valuable for users needing to analyze media data, conduct research, or gather insights based on global news trends.

Settings

The gkgSearch logic component features several configurable settings, which allow users to tailor their search experience. Below is an exhaustive description of each setting:

1. Theme

• Input Type: String
• Description: This setting represents the specific theme or category of interest for the search. Users can specify GKG themes directly or use a custom theme that they input.
• Impact: If set, this theme is the primary filter for the search results and influences the articles returned. Specifying a more precise theme typically yields more relevant search results.
• Default Value: An empty string (''), which means no theme is applied until specified.

2. Query

• Input Type: String
• Description: This search field allows users to input specific keywords for the search. It complements the theme setting by providing an additional filter for the articles searched.
• Impact: When a query is provided, it is appended to the search criteria, thereby narrowing down results based on the entered keywords.
• Default Value: An empty string (''); the search will not utilize specific keywords unless defined by the user.

3. Timespan

• Input Type: String
• Description: This setting defines the period in which articles should be retrieved, formatted typically as a duration (e.g., 1d for one day).
• Impact: Shortening the timespan can limit results to more recent articles, which is beneficial for capturing current events. Conversely, increasing the timespan may yield a broader array of articles.
• Default Value: 1d (one day).

4. Max Records

• Input Type: Numeric
• Description: Specifies the maximum number of articles to return in the search results.
• Impact: Adjusting this value changes the volume of results. A higher number may provide more data for analysis but can also introduce noise, while a lower number fine-tunes the search to the most relevant hits.
• Default Value: 50 (maximum number of articles returned).

5. Sort

• Input Type: String
• Description: Determines the order in which the search results are returned. Common sorting options include date (ascending or descending).
• Impact: Changing this to a different sorting parameter will alter the arrangement of returned articles, making the newest or oldest articles appear first based on the specification.
• Default Value: datedesc (results sorted by date in descending order).

6. Country

• Input Type: String
• Description: Filters search results based on the country of origin for the articles. This could be useful for regional analysis.
• Impact: Specifying a country narrows the output to relevant articles from that specific nation.
• Default Value: An empty string (''), meaning no geographic filter unless specified.

7. Language

• Input Type: String
• Description: Designates the language of the articles to be retrieved.
• Impact: Limiting results to a specific language can provide targeted insights relevant to users working within linguistic constraints.
• Default Value: An empty string (''), implying no language filter is applied unless the user sets it.

How it Works

When the gkgSearch function is executed, it orchestrates the following steps:

1. Input Collection: It collects input values from inputs and config for themes and queries.

2. Query Construction: A search configuration object (searchConfig) is built by combining the theme, query, and additional parameters such as timespan, max records, sort options, country, and language.

3. Validation: The function checks if at least one of the theme or query parameters has been provided. If not, it returns an error message prompting the user to supply either a GKG theme or a search query.

4. Article Retrieval: It calls the searchArticles function using the constructed searchConfig object to fetch relevant articles.

5. Error Handling: If an error occurs during the API call, the function captures the error message and returns it as part of the output.

6. Data Output: The output returns either the list of articles that match the search criteria or a default message indicating no results were found.

Use Cases & Examples

Use Cases

1. Market Research: A business analyst can use this component to gather insights on public sentiment related to a specific product by querying articles containing the product name as a keyword. The articles can help identify trends and consumer feedback.

2. Event Tracking: Journalists could use the gkgSearch to monitor coverage of significant events, such as a climate change conference, by searching using specific GKG themes related to the event.

3. Academic Research: Researchers could search for articles on particular themes, like "social media impacts on youth," to support their thesis with relevant literature and case studies.

Example Configuration

Use Case - Monitoring Public Sentiment on a Product Launch

Objective: A company wants to track public response to its new product launch, launching a campaign to measure customer reaction through news articles.

Configuration Data:

{
    "inputs": {},
    "config": {
        "theme": "Product Launch",
        "query": "New XYZ Product",
        "timespan": "7d",
        "maxRecords": 100,
        "sort": "datedesc",
        "country": "US",
        "language": "en"
    }
}

Explanation:

• Theme: Set to "Product Launch" to broadly categorize articles related to the event.
• Query: "New XYZ Product" focuses on the specific product being launched.
• Timespan: Limited to the last 7 days to capture immediate reactions and coverage.
• Max Records: Set to 100 to allow for a thorough collection of diverse articles.
• Sort: Ordered by date in descending order for the latest articles to appear first.
• Country: Filtered to the US to ensure the relevance of regional coverage.
• Language: Set to English for targeting the intended audience.

By configuring gkgSearch in this manner, the company can effectively gather insights from varied news articles, helping them analyze customer trends and public relations effectively.