Python SDK Specification

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.

python

    pip install desearch-py

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

python

from desearch_py import Desearch
import os

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

📘 API Keys

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 users a feature to search for both links and summaries over different tools.

Example Usage

python

result = desearch.ai_search(
        prompt="Bittensor",
        tools=[
            "web",
            "hackernews",
            "reddit",
            "wikipedia",
            "youtube",
            "twitter",
            "arxiv"
        ],
        date_filter="PAST_24_HOURS",
        streaming=False,
        count=10,
    )

Input Parameters

Parameter	Type	Description	Default
prompt	string	Search query prompt	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”]
date_filter	Optional[string]	The date filter to be used for the search	LINKS_FIRST
streaming	Optional[bool]	Whether to stream results	True
count	Optional[int]	The number of results to return per source. Min 10. Max 200.	10

Sample Response

json

{
        "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 the 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 by leveraging AI-powered models. This API analyzes 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

python

result = desearch.twitter_links_search(
  			prompt="Bittensor"
				count=10,
    )

Input Parameters

Parameter	Type	Description	Default
prompt	str	Search query prompt	Bittensor
count	int	The number of results to return per source. Min 10. Max 200.	10

Sample Response

json

{
        "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

python

result = desearch.web_links_search(
        prompt="Bittensor",
        tools=[
            "web",
            "hackernews",
            "reddit",
            "wikipedia",
            "youtube",
            "arxiv"
        ],
				count=10
    )

Input Parameters

Parameter	Type	Description	Default
prompt	string	Search query prompt	Bittensor
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”]
count	int	The number of results to return per source. Min 10. Max 200.	10

Sample Response

json

{
        "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 analyzes links from X (Twitter) posts that match the given prompt.

Input Example

python

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

json

[
        {
            "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 on the web. This replicates a typical search engine experience, where users can search for any information they need.

Example Usage

python

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

json

{
    "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."
            ]
            }
        ]
    }

Check out example use cases here:

desearch-py-examples

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

Check out example use cases here:

🍪 We value your privacy

`ai_search` Method

`twitter_links_search` Method

`BasicWebSearch` Method

`basic_twitter_search` Method

`basic_web_search` Method