The Desearch Python SDK provides a seamless way to integrate AI-powered search functionalities into your applications. This guide outlines the installation process, available methods, and example implementations.

Installation

To install the desearch-py SDK, use the following command:

    pip install desearch-py

Once installed, you can instantiate the Desearch client as follows:

    from desearch_py import Desearch
    import os

    desearch = Desearch(api_key=os.getenv('your-api-key'))

API Key: Get API Key (Follow link to get your API key) https://console.desearch.ai/api-keys.

Methods and Usage

The Desearch Python SDK provides the following methods for AI-powered search:

`ai_search` Method

This endpoint provides user a feature to search for both links and summary over different tools.

Example Usage

    result = desearch.ai_search(
        prompt="Bittensor",
        tools=[
            "Web Search",
            "Hacker News Search",
            "Reddit Search",
            "Wikipedia Search",
            "Youtube Search",
            "Twitter Search",
            "ArXiv Search"
        ],
        model="NOVA",
        date_filter="PAST_24_HOURS",
        streaming=False,
    )

Input Parameters

Parameter	Type	Description	Default
prompt	string	Search query promp	Bittensor
tools	List[string]	A list of tools to be used for the search	[“Web Search”, “Hacker News Search”, “Reddit Search”, “Wikipedia Search”, “Youtube Search”, “Twitter Search”, “ArXiv Search”]
model	string	The model to be used for the search	NOVA
date_filter	Optional[string]	The date filter to be used for the search	LINKS_FIRST
streaming	Optional[bool]	Whether to stream results	True

Sample Response

    {
        "youtube_search_results": {
            "organic_results": [
            {
                "title": "Did The FED Do The Impossible? [Huge Implications For Bitcoin]",
                "link": "https://www.youtube.com/watch?v=Ycq1u2zWfr8",
                "snippet": "Did we avoid a recession and is there still more upside for Bitcoin? GET MY FREE NEWSLETTER ...",
                "summary_description": "Did The FED Do The Impossible? [Huge Implications For Bitcoin]"
            }
            ]
        },
        "hacker_news_search_results": {
            "organic_results": [
            {
                "title": "latest",
                "link": "https://news.ycombinator.com/latest?id=42816511",
                "snippet": "The streaming app for the Paris Olympics was a revolution from which I can never go back to OTA coverage. I watched so many more competitions ...",
                "summary_description": ""
            }
            ]
        },
        "reddit_search_results": {
            "organic_results": [
            {
                "title": "6 New Sports at Los Angeles 2028 Olympics",
                "link": "https://www.reddit.com/r/olympics/comments/1ert9av/6_new_sports_at_los_angeles_2028_olympics/",
                "snippet": "Baseball and softball are not new olympic sports, but returning. Up to Tokyo, baseball was at every olympics since 1984 except London and Rio.",
                "summary_description": ""
            }
            ]
        },
        "arxiv_search_results": {
            "organic_results": [
            {
                "title": "[2304.02655] Deciphering the Blockchain: A Comprehensive Analysis of Bitcoin's Evolution, Adoption, and Future Implications",
                "link": "https://arxiv.org/abs/2304.02655",
                "snippet": "Abstract page for arXiv paper 2304.02655: Deciphering the Blockchain: A Comprehensive Analysis of Bitcoin's Evolution, Adoption, and Future Implications",
                "with_metadata": true,
                "summary_description": "[2304.02655] Deciphering the Blockchain: A Comprehensive Analysis of Bitcoin's Evolution, Adoption, and Future Implications"
            }
            ]
        },
        "wikipedia_search_results": {
            "organic_results": [
            {
                "title": "List of bitcoin companies - Wikipedia",
                "link": "https://en.wikipedia.org/wiki/List_of_Bitcoin_companies",
                "snippet": "",
                "with_metadata": true,
                "summary_description": "List of bitcoin companies - Wikipedia"
            }
            ]
        },
        "text_chunks": {
            "twitter_summary": [
            "<string>"
            ]
        },
        "search_completion_links": [
            "https://www.youtube.com/watch?v=Ycq1u2zWfr8",
            "https://news.ycombinator.com/latest?id=42816511",
            "https://www.reddit.com/r/olympics/comments/1ert9av/6_new_sports_at_los_angeles_2028_olympics/",
            "https://en.wikipedia.org/wiki/List_of_Bitcoin_companies"
        ],
        "completion_links": [
            "https://news.ycombinator.com/latest?id=42816511",
            "https://www.youtube.com/watch?v=Ycq1u2zWfr8"
        ],
        "completion": {
            "key_posts": [
            {
                "text": "This is an example post text.",
                "url": "https://x.com/example_post"
            }
            ],
            "key_tweets": [
            {
                "text": "This is an example tweet text.",
                "url": "https://x.com/example_tweet"
            }
            ],
            "key_news": [
            {
                "text": "This is an example news text.",
                "url": "https://news.example.com/123"
            }
            ],
            "key_sources": [
            {
                "text": "This is an example source text.",
                "url": "https://www.example.com"
            }
            ],
            "twitter_summary": "This is an example Twitter summary.",
            "summary": "This is an example summary.",
            "reddit_summary": "This is an example summary.",
            "hacker_news_summary": "This is an example summary."
        }
    }

Here are the details of above response. The return type depends on the combination of text and highlights parameters:

A JSON object mapping tool names to their search results: When only streaming is False
StreamingResponse(text_chunks): When only streaming is True

`twitter_links_search` Method

The X (Twitter) Posts Search API allows users to search for relevant links based on X (Twitter) search queries with leveraging AI-powered models. This API analyze links from X (Twitter) posts that match the given prompt. This API is useful for tracking trends, gathering insights, and retrieving real-time information from X (Twitter).

Example Usage

    result = desearch.twitter_links_search(
        prompt="Bittensor",
        model="NOVA",
    )

Input Parameters

Parameter	Type	Description	Default
prompt	str	Search query promp	Bittensor
model	str	The model to be used for the search	NOVA

Sample Response

    {
        "miner_tweets": [
            {
            "user": {
                "id": "123456789",
                "url": "https://twitter.com/example_user",
                "name": "John Doe",
                "username": "johndoe",
                "created_at": "2023-01-01T00:00:00Z",
                "description": "This is an example user description.",
                "favourites_count": 100,
                "followers_count": 1500,
                "listed_count": 10,
                "media_count": 50,
                "profile_image_url": "https://example.com/profile.jpg",
                "statuses_count": 500,
                "verified": true
            },
            "id": "987654321",
            "text": "This is an example tweet.",
            "reply_count": 10,
            "retweet_count": 5,
            "like_count": 100,
            "view_count": 1000,
            "quote_count": 2,
            "impression_count": 1500,
            "bookmark_count": 3,
            "url": "https://twitter.com/example_tweet",
            "created_at": "2023-01-01T00:00:00Z",
            "media": [],
            "is_quote_tweet": false,
            "is_retweet": false,
            "entities": {},
            "summary_description": "This is a summary of the tweet."
            }
        ]
    }

`BasicWebSearch` Method

This API allows users to search for links related to a given query (prompt) using multiple tools, excluding X (Twitter) Search. The API returns a list of relevant sources from selected platforms such as web pages, YouTube, Wikipedia, and ArXiv.

Example Usage

    result = desearch.web_links_search(
        prompt="Bittensor",
        tools=[
            "Web Search",
            "Hacker News Search",
            "Reddit Search",
            "Wikipedia Search",
            "Youtube Search",
            "Twitter Search",
            "ArXiv Search"
        ],
        model="NOVA",
    )

Input Parameters

Parameter	Type	Description	Default
prompt	string	Search query promp	Bittensor
model	string	The model to be used for the search	NOVA
tools	List[string]	List of tools to search with An enumeration.	[ “Web Search”, “Hacker News Search”,“Reddit Search”,“Wikipedia Search”,“Youtube Search”,“Twitter Search”, “ArXiv Search”]

Sample Response

    {
        "youtube_search_results": [
            {
            "title": "Did The FED Do The Impossible? [Huge Implications For Bitcoin]",
            "link": "https://www.youtube.com/watch?v=Ycq1u2zWfr8",
            "snippet": "Did we avoid a recession and is there still more upside for Bitcoin? GET MY FREE NEWSLETTER ...",
            "summary_description": "Did The FED Do The Impossible? [Huge Implications For Bitcoin]"
            }
        ],
        "hacker_news_search_results": {
            "organic_results": [
            {
                "position": 1,
                "title": "latest",
                "link": "https://news.ycombinator.com/latest?id=42816511",
                "redirect_link": "https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://news.ycombinator.com/latest%3Fid%3D42816511&ved=2ahUKEwiVgOLj45qLAxVJkIkEHQHrOzwQFnoECAgQAQ",
                "displayed_link": "https://news.ycombinator.com › latest",
                "favicon": "https://serpapi.com/searches/679a0a9dc12f1fe12103d57c/images/6e61b1f70b2f0d460b331310ebc59ded6780dc83d9e6763c5e07eea31b8c9155.png",
                "date": "17 hours ago",
                "snippet": "The streaming app for the Paris Olympics was a revolution from which I can never go back to OTA coverage. I watched so many more competitions ...",
                "snippet_highlighted_words": [
                "competitions"
                ],
                "source": "Hacker News"
            }
            ]
        },
        "reddit_search_results": {
            "organic_results": [
            {
                "position": 2,
                "title": "6 New Sports at Los Angeles 2028 Olympics",
                "link": "https://www.reddit.com/r/olympics/comments/1ert9av/6_new_sports_at_los_angeles_2028_olympics/",
                "redirect_link": "https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://www.reddit.com/r/olympics/comments/1ert9av/6_new_sports_at_los_angeles_2028_olympics/&ved=2ahUKEwiFyNfj45qLAxUBLFkFHd0hOr0QFnoECCIQAQ",
                "displayed_link": "2.7K+ comments · 5 months ago",
                "favicon": "https://serpapi.com/searches/679a0a9da515cccc50df9203/images/a48c8b9ec22ae0600eaafcee75444cac0b05a09b6c4f36ae69a23b1ec299d102.png",
                "snippet": "Baseball and softball are not new olympic sports, but returning. Up to Tokyo, baseball was at every olympics since 1984 except London and Rio.",
                "snippet_highlighted_words": [
                "sports"
                ],
                "source": "Reddit · r/olympics"
            }
            ]
        },
        "arxiv_search_results": [
            {
            "title": "[2304.02655] Deciphering the Blockchain: A Comprehensive Analysis of Bitcoin's Evolution, Adoption, and Future Implications",
            "link": "https://arxiv.org/abs/2304.02655",
            "snippet": "Abstract page for arXiv paper 2304.02655: Deciphering the Blockchain: A Comprehensive Analysis of Bitcoin's Evolution, Adoption, and Future Implications",
            "with_metadata": true,
            "summary_description": "[2304.02655] Deciphering the Blockchain: A Comprehensive Analysis of Bitcoin's Evolution, Adoption, and Future Implications"
            }
        ],
        "wikipedia_search_results": [
            {
            "title": "List of bitcoin companies - Wikipedia",
            "link": "https://en.wikipedia.org/wiki/List_of_Bitcoin_companies",
            "snippet": "",
            "with_metadata": true,
            "summary_description": "List of bitcoin companies - Wikipedia"
            }
        ],
        "search_results": {
            "organic_results": [
            {
                "position": 1,
                "title": "Latest sports news, videos, interviews and comment",
                "link": "https://www.cnn.com/sport",
                "redirect_link": "https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://www.cnn.com/sport&ved=2ahUKEwj5yNTj45qLAxWqHNAFHXpCGUoQFnoECBgQAQ",
                "displayed_link": "https://www.cnn.com › sport",
                "favicon": "https://serpapi.com/searches/679a0a9dca85264e50d1e39f/images/e52955875acc356934b40dfd33c4b0e8191710f0c1b820d80a006163f68f2197.png",
                "snippet": "Latest sports news from around the world with in-depth analysis, features, photos and videos covering football, tennis, motorsport, golf, rugby, sailing, ...",
                "snippet_highlighted_words": [
                "Latest sports"
                ],
                "sitelinks": {
                "inline": [
                    {
                    "title": "Football",
                    "link": "https://www.cnn.com/sport/football"
                    },
                    {
                    "title": "Tennis",
                    "link": "https://www.cnn.com/sport/tennis"
                    },
                    {
                    "title": "Golf",
                    "link": "https://www.cnn.com/sport/golf"
                    },
                    {
                    "title": "US Sports",
                    "link": "https://www.cnn.com/sport/us-sports"
                    }
                ]
                },
                "source": "CNN"
            }
            ]
        }
        }

`basic_twitter_search` Method

The Basic X (Twitter) Search API allows users to search for relevant links or tweets based on X (Twitter) search queries without leveraging AI-powered models. This API analyze links from X (Twitter) posts that match the given prompt.

Input Example:

    result = desearch.basic_twitter_search(
        query="Whats going on with Bittensor",
        sort="Top",
        user="elonmusk",
        start_date="2024-12-01",
        end_date="2025-02-25",
        lang="en",
        verified=True,
        blue_verified=True,
        is_quote=True,
        is_video=True,
        is_image=True,
        min_retweets=1,
        min_replies=1,
        min_likes=1
        count=10
    )

Input Parameters

Parameter	Type	Description	Default
query	string	Search query. For syntax, check https://docs.desearch.ai/guides/capabilities/twitter-queries	Whats going on with Bittensor
sort	string	Sort order of the search results	Top
user	string	User to search for tweets	elonmusk
start_date	string	Start date for the search (YYYY-MM-DD format)	2024-12-01
end_date	string	End date for the search (YYYY-MM-DD format)	2025-02-25
lang	string	Language of the tweets (e.g., en, es, fr)	en
verified	bool	Filter for verified users	true
blue_verified	bool	Filter for blue verified users	true
is_quote	bool	Filter for quoted tweets	true
is_video	bool	Filter for video tweets	true
is_image	bool	Filter for image tweets	true
min_retweets	int	Minimum number of retweets	0
min_replies	int	Minimum number of replies	0
min_likes	int	Minimum number of likes	0
count	int	Number of tweets to retrieve	10

Sample Response

    [
        {
            "user": {
            "id": "123456789",
            "url": "https://twitter.com/example_user",
            "name": "John Doe",
            "username": "johndoe",
            "created_at": "2023-01-01T00:00:00Z",
            "description": "This is an example user description.",
            "favourites_count": 100,
            "followers_count": 1500,
            "listed_count": 10,
            "media_count": 50,
            "profile_image_url": "https://example.com/profile.jpg",
            "statuses_count": 500,
            "verified": true
            },
            "id": "987654321",
            "text": "This is an example tweet.",
            "reply_count": 10,
            "retweet_count": 5,
            "like_count": 100,
            "view_count": 1000,
            "quote_count": 2,
            "impression_count": 1500,
            "bookmark_count": 3,
            "url": "https://twitter.com/example_tweet",
            "created_at": "2023-01-01T00:00:00Z",
            "media": [],
            "is_quote_tweet": false,
            "is_retweet": false
        }
    ]

`basic_web_search` Method

This API allows users to search for any information over the web. This replicates a typical search engine experience, where users can search for any information they need.

Example Usage

    result = desearch.basic_web_search(
        query="latest news on AI",
        num=10,
        start=0
    )

Input Parameters

Parameter	Type	Description	Default
query	str	The search query string, e.g., ‘latest news on AI’	latest news on AI
num	int	Count of results to get	10
start	int	How many results to skip (used for pagination with num)	0

Sample Response

    {
    "data": [
            {
            "title": "EXCLUSIVE Major coffee buyers face losses as Colombia ...",
            "snippet": "Coffee farmers in Colombia, the world's No. 2 arabica producer, have failed to deliver up to 1 million bags of beans this year or nearly 10% ...",
            "link": "https://www.reuters.com/world/americas/exclusive-major-coffee-buyers-face-losses-colombia-farmers-fail-deliver-2021-10-11/",
            "date": "21 hours ago",
            "source": "Reuters",
            "author": "Reuters",
            "image": "https://static.reuters.com/resources/2021/10/11/Reuters/Reuters_20211011_0000_01.jpg?w=800&h=533&q=80&crop=1",
            "favicon": "https://static.reuters.com/resources/2021/10/11/Reuters/Reuters_20211011_0000_01.jpg?w=800&h=533&q=80&crop=1",
            "highlights": [
                "Such requests are not allowed."
            ]
            }
        ]
    }

Introduction

Desearch APIs

Desearch SDKs

Desearch APIFY Actors

Use Cases

Capabilities

Python SDK Specification

Installation

Methods and Usage

`ai_search` Method

Example Usage

Input Parameters

Sample Response

`twitter_links_search` Method

Example Usage

Input Parameters

Sample Response

`BasicWebSearch` Method

Example Usage

Input Parameters

Sample Response

`basic_twitter_search` Method

Input Example:

Input Parameters

Sample Response

`basic_web_search` Method

Example Usage

Input Parameters

Sample Response

Introduction

Desearch APIs

Desearch SDKs

Desearch APIFY Actors

Use Cases

Capabilities

​Installation

​Methods and Usage

​ai_search Method

​Example Usage

​Input Parameters

​Sample Response

​twitter_links_search Method

​Example Usage

​Input Parameters

​Sample Response

​BasicWebSearch Method

​Example Usage

​Input Parameters

​Sample Response

​basic_twitter_search Method

​Input Example:

​Input Parameters

​Sample Response

​basic_web_search Method

​Example Usage

​Input Parameters

​Sample Response

Installation

Methods and Usage

`ai_search` Method

Example Usage

Input Parameters

Sample Response

`twitter_links_search` Method

Example Usage

Input Parameters

Sample Response

`BasicWebSearch` Method

Example Usage

Input Parameters

Sample Response

`basic_twitter_search` Method

Input Example:

Input Parameters

Sample Response

`basic_web_search` Method

Example Usage

Input Parameters

Sample Response