Image Search Documentation

Purpose

The imageSearch logic facilitates the retrieval of news images from the GDELT Visual Global Knowledge Graph (VGKG) based on a user-defined query. It processes the request and delivers image URLs alongside their corresponding source metadata, thus allowing users to leverage visual data effectively for various analytics and reporting purposes.

Settings

The imageSearch logic includes several configurable settings that determine its behavior and output. Below are the settings explained exhaustively:

1. query

• Input Type: String
• Description: This setting represents the search term or phrase that will be used to search for related images in the GDELT dataset.
• Impact: Adjusting this setting changes the results retrieved from the image search. A more specific query will yield more relevant images, while a vague query may return a broader set of images.
• Default Value: An empty string (''). If no query is provided, the logic will return an error indicating that no search query was supplied.

2. timespan

• Input Type: String
• Description: Specifies the time frame for which the image search should be conducted. This defines the period during which the images should be published or from which the news should originate.
• Impact: Changing this value will affect the images returned; for instance, using a timespan of '1w' (one week) limits results to that week only, while '1m' (one month) expands it accordingly.
• Default Value: '1d', which restricts the search to images published within the last day.

3. maxRecords

• Input Type: Numeric
• Description: Defines the maximum number of image records to be retrieved in a single query. This cap helps manage the volume of data returned and aids in performance optimization.
• Impact: Increasing this number allows more images to be fetched, while decreasing it limits the results, which may be useful while handling large datasets or maintaining performance.
• Default Value: 75. This means that up to 75 image records will be returned by default unless specified otherwise.

How It Works

When executed, the imageSearch logic accepts an input object containing user-defined config parameters. The logic performs the following steps:

1. Configuration Setup: It initializes the searchConfig object, setting up the search parameters using the values from config or inputs, falling back on defaults if necessary.
2. Validation: It checks if a valid search query has been provided. If not, it returns an error message indicating the absence of the query.
3. Image Retrieval: The function asynchronously calls getImageCollage with the populated searchConfig object. This integration contacts the GDELT service to fetch relevant images.
4. Response Formatting: Based on the outcome of the image retrieval, it formats and returns the results:
   • If images are found, it returns them in an array.
   • If no images are found, it returns a default message indicating the absence of images.
   • In case of any errors during the process (e.g., network issues), it captures the error message and returns it.

Expected Data

The imageSearch function expects the following input data:

• Inputs:
  • Must include a query string that will be used to search for relevant images.
• Configuration:
  • Optional configuration parameters for timespan and maxRecords to customize the search parameters.

Use Cases & Examples

Use Case 1: Journalism

A news organization could utilize imageSearch to pull relevant images for recent stories. By querying specific keywords related to ongoing news events, journalists can acquire up-to-date images to enhance their articles.

Use Case 2: Social Media Analysis

A social media analyst might want to visualize the media associated with particular trending topics. By setting the query to these trending topics, they can collect various images for analysis and presentation.

Example Configuration

Scenario: A marketing team wants to analyze images associated with a newly launched product over the past week.

{
  "inputs": {
    "query": "New Product Launch",
  },
  "config": {
    "timespan": "1w",
    "maxRecords": 50
  }
}

• Inputs: The query field is set to "New Product Launch".
• Config:
  • timespan is set to 1w, meaning the search will only consider images from the past week.
  • maxRecords is limited to 50, which means the output will include up to 50 relevant images.

This configuration enables the marketing team to efficiently analyze relevant imagery surrounding their product launch within a specific timeframe.