trendTimeline Documentation

Purpose

The trendTimeline logic is designed to retrieve and present timeline data regarding the volume, tone, and geographical distribution of specific queries using the GDELT (Global Database of Events, Language, and Tone) DOC 2.0 API. It allows users to analyze trends over a specified timespan, providing insights into event patterns and sentiment expressed in the media, based on their search criteria.

Settings

The trendTimeline logic consists of several configurable settings that dictate its behavior and influence its output. Each setting is detailed below:

1. query

• Input Type: String
• Description: This setting specifies the search term or phrase for which the trend data is retrieved. It is a critical parameter, and if not provided, the logic will terminate execution and return an error.
• Default Value: An empty string ('')

2. timespan

• Input Type: String
• Description: Defines the time range over which the data should be analyzed. The timespan indicates how far back the data should be retrieved from the present day.
• Default Value: '7d' (last 7 days)

3. timelineMode

• Input Type: Dropdown (Enumeration)
• Description: This setting allows users to choose the type of data to visualize over time. Options may include "volume," "tone," or other specific modes available through the GDELT API. Selecting different modes will directly influence the type of analysis performed and displayed.
• Default Value: 'volume'

4. smoothing

• Input Type: Numeric
• Description: Smoothing is used for data representation to achieve a more visually appealing output by averaging data points over a specified range. A higher value results in a smoother trend line, reducing spikes caused by short-term variations in data. Users can set this to ‘0’ (no smoothing) or to any positive integer for increased smoothing.
• Default Value: 0

5. country

• Input Type: String
• Description: This setting allows users to filter the retrieved data based on the specified country. When a country is provided, only events from that location will be factored into the timeline analysis.
• Default Value: An empty string ('')

6. theme

• Input Type: String
• Description: The visual theme for representing the trend data can be specified here. Different themes can affect color schemes and overall styles of the output visualization, enhancing user experience and data interpretation.
• Default Value: An empty string ('')

7. language

• Input Type: String
• Description: This setting allows the user to specify the language of the media sources to be included in the trend analysis. By providing a language code (e.g., "en" for English), users can focus on data that meets their linguistic requirements.
• Default Value: An empty string ('')

How It Works

The trendTimeline logic operates by utilizing the GDELT DOC 2.0 API to fetch relevant timeline data based on user-defined parameters. When the logic is executed:

1. The settings are configured from the provided config object or from the inputs object if the configuration is missing.
2. The code checks if a query has been supplied; if not, it returns an error indicating that no search query was provided.
3. Assuming a valid query is present, it calls the getTimeline function with the compiled configuration settings to fetch the relevant data.
4. The response is processed; if data is found, it returns the timeline data. If no data is returned, it provides a default response with a date, value of 0, and an empty series.
5. If an error occurs during the data retrieval, it returns an error message as part of the output.

Use Cases & Examples

Use Case 1: Monitoring Brand Sentiment

A marketing team wants to monitor the sentiment related to their brand over the past month on social media. By using the trendTimeline, they can analyze how their marketing campaigns are impacting public perception over time.

Use Case 2: Event Analysis for Crisis Management

Government officials need to analyze the volume of reports related to a crisis event (like a natural disaster) to understand media coverage and public response. The trendTimeline can be configured to focus on volume data for a specific geographical area.

Use Case 3: Research in Media Studies

Academics studying media trends can leverage the trendTimeline to investigate how coverage of specific topics changes over time, taking into consideration different tones and how they vary by country.

Detailed Example Configuration:

For the second use case, here’s how the trendTimeline might be configured:

{
    "query": "hurricane",
    "timespan": "30d",
    "timelineMode": "volume",
    "smoothing": 1,
    "country": "US",
    "theme": "dark",
    "language": "en"
}

In this configuration, the trendTimeline will retrieve the last 30 days' worth of media volume data concerning hurricanes in the United States.

Additional Considerations

• AI Integrations: The trendTimeline can be integrated with machine learning models that analyze the retrieved data for predictive insights or sentiment analysis, enhancing decision-making processes.
• Billing Impact: Depending on the usage of the GDELT API, there may be associated costs based on the number of API calls. Users should monitor usage to make sure they stay within their allocated budget for potentially billable API interactions.

This structured documentation will assist users in effectively implementing and utilizing the trendTimeline component to derive actionable insights from media data.