geoMap Documentation

Overview

The geoMap logic is designed to fetch geographic event data and return it as GeoJSON features, leveraging the GDELT (Global Database of Events, Language, and Tone) GEO 2.0 API. This functionality is ideal for visualization on map-based platforms, allowing users to visualize data geographically based on predefined queries and configurable parameters.

Settings

The geoMap logic offers a range of configurable settings that determine how the component operates and displays data. Below are the details for each setting:

1. query

• Input Type: String
• Description: This parameter defines the search query used to fetch GeoJSON features. It plays a critical role as the input to the GDELT API, dictating the content of the data searched and retrieved.
• Default Value: An empty string (''). If no query is provided, the logic will return an error indicating that no search term was given.

2. timespan

• Input Type: String
• Description: This setting specifies the duration for which the data should be collected. It allows users to define a time frame (e.g., '1d' for one day, '1w' for one week) to limit the data returned from the GDELT API.
• Default Value: '1d', which indicates that data from the last day will be queried.

3. country

• Input Type: String
• Description: This optional parameter allows filtering of data based on the specified country. By entering a country code (e.g., 'USA', 'FRA'), the results will include only events related to the selected country.
• Default Value: An empty string (''). If not specified, data will not be limited to a particular country.

4. theme

• Input Type: String
• Description: This setting lets users filter results based on a specific theme or category of events. Themes could include topics like 'climate', 'politics', 'sports', etc. It helps in narrowing down to more relevant data entries based on user interest.
• Default Value: An empty string (''). If no theme is provided, the logic will return data from all themes.

5. language

• Input Type: String
• Description: This setting defines the language of the event data returned by the API. Specifying a language helps in localizing results for user interpretation.
• Default Value: An empty string (''). If not specified, the search will return results in any available language.

Functionality

The run function processes input parameters and invokes the getGeo function from the GDELT service library to obtain geographic event data. If the required query setting is missing, the function returns an error. The retrieved GeoJSON features are then transformed into a tabular format, enabling easy manipulation and downstream processing.

In case of any exceptions during data retrieval, an error message is captured and returned in the output.

Expected Data

The geoMap logic expects the following data types:

• query: A string representing the search terms used to query GDELT.
• timespan: A string indicating the duration for which data is retrieved (defaulting to '1d').
• country: A string that represents an optional filter for geographical data.
• theme: A string used to filter results by category.
• language: A string specifying the desired language for the event data.

The output will be an array of objects that contain details such as event name, geographic lat and lon coordinates, count of occurrences, url providing additional information, source of the data, and tone associated with the events.

Use Cases & Examples

Use Case 1: Monitoring Global News Events

A global news organization can utilize the geoMap to visualize significant event occurrences around the world, filtering events based on specific themes such as "politics" or "environment". This allows reporters to quickly identify areas of interest and develop stories based on real-time data.

Use Case 2: Crowd Management for Large Events

Event organizers can leverage the geoMap to track crowd movements and assemble geographic event data for occasions like concerts or sports events. By monitoring real-time happenings, they can manage crowd control effectively, directing attendees when necessary.

Use Case 3: Research on Environmental Events

A research organization can use the geoMap to visualize and analyze environmental events globally. They can filter by specific themes related to climate issues and view patterns over selected time frames.

Example Configuration for Use Case 1: Monitoring Global News Events

To set up the geoMap for visualizing major political events from the past week, one might configure it as follows:

{
    "query": "politics",
    "timespan": "1w",
    "country": "USA",
    "theme": "politics",
    "language": "en"
}

In this configuration:

• The search is specifically tailored to political events.
• Data will be fetched for the one-week duration.
• Results will be filtered to reflect only those related to the USA and tailored to the English language.

This setup provides a focused and manageable way to visualize recent political trends and important news stories.