Unlocking Real-Time Web Search with Cognitive Actions

22 Apr 2025
Unlocking Real-Time Web Search with Cognitive Actions

In today's fast-paced digital environment, retrieving timely and relevant information is crucial for applications and services. The Real-Time Web Search API provides developers with powerful Cognitive Actions that enable seamless integration of real-time search capabilities into their applications. By leveraging these pre-built actions, developers can enhance user experiences with immediate access to the latest web content, tailored to specific queries and parameters.

Prerequisites

Before diving into the integration of the Real-Time Web Search actions, ensure you have the following:

  • An API key for the Cognitive Actions platform, which will be used for authentication.
  • Familiarity with JSON format, as the input and output structures will be in JSON.
  • Basic knowledge of making HTTP requests in your programming language of choice (in this case, we'll provide a Python example).

To authenticate, you will typically pass your API key in the headers of your HTTP requests.

Cognitive Actions Overview

This action retrieves real-time organic search results from Google. It supports advanced features like location-based geo-targeting and the use of Google Advanced Search operators for refined query results.

Input

The input for this action requires the following fields, with some being optional:

  • query (required): The main search query string. Defaults to "how to build a website".
  • start (optional): The starting index of the search results. Defaults to 0 for pagination.
  • language (optional): The language code for the search query, defaults to "en" for English.
  • location (optional): The specific location to refine the search results.
  • geoLocation (optional): The geographical region where the search should be performed. Defaults to "us".
  • numberOfResults (optional): The number of search results to return. Default is 10.
  • timeBasedSearch (optional): Specify a time range for the search results.

Example Input:

{
  "query": "how to build a website",
  "start": 0,
  "language": "en",
  "geoLocation": "us",
  "numberOfResults": 10
}

Output

The action typically returns a JSON object containing an array of search results. Each result includes:

  • url: The URL of the search result.
  • rank: The rank position of the result.
  • title: The title of the webpage.
  • source: The source of the content.
  • snippet: A brief description or snippet of the content.
  • position: The position of the result in the list.

Example Output:

{
  "data": [
    {
      "url": "https://www.canva.com/website-builder/",
      "rank": 1,
      "title": "Website Builder - Create a Free Website - Canva",
      "source": "Canva",
      "snippet": "Design and launch a professional, one-of-a-kind website in minutes with Canva's free website builder...",
      "position": 1
    },
    {
      "url": "https://www.reddit.com/r/learnprogramming/comments/12mvjym/how_to_make_a_website_for_freemyselfon_my_own/",
      "rank": 2,
      "title": "How to make a website for free/myself/on my own? - Reddit",
      "source": "Reddit · r/learnprogramming",
      "snippet": "I would recommend starting with HTML, CSS, and JavaScript...",
      "position": 2
    }
    // Additional results...
  ],
  "status": "OK",
  "parameters": {
    "q": "how to build a website",
    "gl": "us",
    "hl": "en",
    "num": 10,
    "start": 0
  },
  "request_id": "b28ed959-6604-4c9a-9d5b-420aa1595a06"
}

Conceptual Usage Example (Python)

Here's how you might call this action using Python:

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute" # Hypothetical endpoint

action_id = "b664475a-e327-47fe-b7d0-22c7eecc67d7"  # Action ID for Perform Real-Time Google Web Search

# Construct the input payload based on the action's requirements
payload = {
  "query": "how to build a website",
  "start": 0,
  "language": "en",
  "geoLocation": "us",
  "numberOfResults": 10
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload}  # Hypothetical structure
    )
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

In this code snippet, replace the API key and endpoint as needed. The action ID is specified for the Real-Time Web Search, and the input payload is constructed using the required fields.

Conclusion

Integrating the Real-Time Web Search Cognitive Actions into your applications not only enhances the user experience but also ensures that your application provides the latest and most relevant information available. By utilizing these actions, developers can create powerful search functionalities that cater to user needs effectively. Next steps may include exploring more advanced search parameters or combining this action with other Cognitive Actions to create a comprehensive search solution. Happy coding!

← Back to All Articles