Skip to content
Back to search

ddgs

A metasearch library that aggregates results from diverse web search services

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/deedy5--ddgs/badge.svg)](/listings/deedy5--ddgs)

HTML

<a href="/listings/deedy5--ddgs"><img src="/api/listings/deedy5--ddgs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install -U ddgs       # Base install
pip install -U ddgs[api]  # API server (FastAPI)
pip install -U ddgs[mcp]  # MCP server (stdio)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 497 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Python >= 3.10](https://img.shields.io/badge/python->=3.10-red.svg) [![](https://badgen.net/github/release/deedy5/ddgs)](https://github.com/deedy5/ddgs/releases) [![](https://badge.fury.io/py/ddgs.svg)](https://pypi.org/project/ddgs)
  2. # DDGS | Dux Distributed Global Search<a name="TOP"></a>
  3. A metasearch library that aggregates results from diverse web search services.
  4. ## Table of Contents
  5. * [Install](#install)
  6. * [CLI version](#cli-version)
  7. * [API Server](#api-server)
  8. * [MCP Server](#mcp-server)
  9. * [Engines](#engines)
  10. * [DDGS class](#ddgs-class)
  11. * [1. text()](#1-text)
  12. * [2. images()](#2-images)
  13. * [3. videos()](#3-videos)
  14. * [4. news()](#4-news)
  15. * [5. books()](#5-books)
  16. * [6. extract()](#6-extract)
  17. * [Disclaimer](#disclaimer)
  18. ___
  19. ## Install
  20. ```python
  21. pip install -U ddgs # Base install
  22. pip install -U ddgs[api] # API server (FastAPI)
  23. pip install -U ddgs[mcp] # MCP server (stdio)
  24. ```
  25. ## CLI version
  26. ```python3
  27. ddgs - -help
  28. ```
  29. [Go To TOP](#TOP)
  30. ___
  31. ## API Server
  32. -- **Install**
  33. ```bash
  34. pip install -U ddgs[api]
  35. ```
  36. -- **CLI**
  37. ```bash
  38. ddgs api # Start server in foreground
  39. ddgs api -d # Start in detached mode (background)
  40. ddgs api -s # Stop detached server
  41. ddgs api --host 127.0.0.1 --port 4479 # Default port 4479
  42. ddgs api -pr socks5h://127.0.0.1:9150 # With proxy
  43. ```
  44. -- **Docker compose**
  45. ```bash
  46. git clone https://github.com/deedy5/ddgs && cd ddgs
  47. docker-compose up --build
  48. ```
  49. -- **Bash script**
  50. ```bash
  51. git clone https://github.com/deedy5/ddgs && cd ddgs
  52. chmod +x start_api.sh
  53. ./start_api.sh
  54. ```
  55. #### Endpoints
  56. | Endpoint | Method | Description |
  57. |----------|--------|-------------|
  58. | `/search/text` | GET, POST | Text search |
  59. | `/search/images` | GET, POST | Image search |
  60. | `/search/news` | GET, POST | News search |
  61. | `/search/videos` | GET, POST | Video search |
  62. | `/search/books` | GET, POST | Book search |
  63. | `/extract` | GET, POST | Extract content from URL |
  64. | `/health` | GET | Health check |
  65. | `/docs` | GET | Swagger UI |
  66. | `/redoc` | GET | ReDoc documentation |
  67. [Go To TOP](#TOP)
  68. ___
  69. ## MCP Server
  70. - **Install**
  71. ```bash
  72. pip install -U ddgs[mcp]
  73. ```
  74. - **CLI**
  75. ```bash
  76. ddgs mcp # Start MCP server (stdio transport)
  77. ddgs mcp -pr socks5h://127.0.0.1:9150 # With proxy
  78. ```
  79. #### Available Tools
  80. | Tool | Description |
  81. |------|-------------|
  82. | `search_text` | Web text search |
  83. | `search_images` | Image search |
  84. | `search_news` | News search |
  85. | `search_videos` | Video search |
  86. | `search_books` | Book search |
  87. | `extract_content` | Extract content from a URL |
  88. #### Client Configuration
  89. For MCP clients like Cursor or Claude Desktop:
  90. ```json
  91. {
  92. "mcpServers": {
  93. "ddgs": {
  94. "command": "ddgs",
  95. "args": ["mcp"]
  96. }
  97. }
  98. }
  99. ```
  100. [Go To TOP](#TOP)
  101. ___
  102. ## Engines
  103. | DDGS function | Available backends |
  104. | --------------|:-------------------|
  105. | text() | `bing`, `brave`, `duckduckgo`, `google`, `grokipedia`, `mojeek`, `startpage`, `yandex`, `yahoo`, `wikipedia`|
  106. | images() | `bing`, `duckduckgo` |
  107. | videos() | `duckduckgo` |
  108. | news() | `bing`, `duckduckgo`, `yahoo` |
  109. | books() | `annasarchive` |
  110. [Go To TOP](#TOP)
  111. ## DDGS class
  112. DDGS class is lazy-loaded.
  113. ```python3
  114. class DDGS:
  115. """Dux Distributed Global Search. A metasearch library that aggregates results from diverse web search services.
  116. Args:
  117. proxy (str, optional): proxy for the HTTP client, supports http/https/socks5 protocols.
  118. example: "http://user:pass@example.com:3128". Defaults to None.
  119. timeout (int, optional): Timeout value for the HTTP client. Defaults to 5.
  120. verify: (bool | str): True to verify, False to skip, or a str path to a PEM file. Defaults to True.
  121. """
  122. ```
  123. Here is an example of initializing the DDGS class.
  124. ```python3
  125. from ddgs import DDGS
  126. results = DDGS().text("python programming", max_results=5)
  127. print(results)
  128. ```
  129. [Go To TOP](#TOP)
  130. ## 1. text()
  131. ```python
  132. def text(
  133. query: str,
  134. region: str = "us-en",
  135. safesearch: str = "moderate",
  136. timelimit: str | None = None,
  137. max_results: int | None = 10,
  138. page: int = 1,
  139. backend: str = "auto",
  140. ) -> list[dict[str, str]]:
  141. """DDGS text metasearch.
  142. Args:
  143. query: text search query.
  144. region: us-en, uk-en, ru-ru, etc. Defaults to us-en.
  145. safesearch: on, moderate, off. Defaults to "moderate".
  146. timelimit: d, w, m, y. Defaults to None.
  147. max_results: maximum number of results. Defaults to 10.
  148. page: page of results. Defaults to 1.
  149. backend: A single or comma-delimited backends. Defaults to "auto".
  150. Returns:
  151. List of dictionaries with search results.
  152. """
  153. ```
  154. ***Example***
  155. ```python
  156. results = DDGS().text("live free or die", region="us-en", safesearch="off", timelimit="y", page=1, backend="auto")
  157. # Searching for pdf files
  158. results = DDGS().text("russia filetype:pdf", region="us-en", safesearch="off", timelimit="y", page=1, backend="auto")
  159. print(results)
  160. [
  161. {
  162. "title": "News, sport, celebrities and gossip | The Sun",
  163. "href": "https://www.thesun.co.uk/",
  164. "body": "Get the latest news, exclusives, sport, celebrities, showbiz, politics, business and lifestyle from The Sun",
  165. },
  166. ...,
  167. ]
  168. ```
  169. [Go To TOP](#TOP)
  170. ## 2. images()
  171. ```python
  172. def images(
  173. query: str,
  174. region: str = "us-en",
  175. safesearch: str = "moderate",
  176. timelimit: str | None = None,
  177. max_results: int | None = 10,
  178. page: int = 1,
  179. backend: str = "auto",
  180. size: str | None = None,
  181. color: str | None = None,
  182. type_image: str | None = None,
  183. layout: str | None = None,
  184. license_image: str | None = None,
  185. ) -> list[dict[str, str]]:
  186. """DDGS images metasearch.
  187. Args:
  188. query: images search query.
  189. region: us-en, uk-en, ru-ru, etc. Defaults to us-en.
  190. safesearch: on, moderate, off. Defaults to "moderate".
  191. timelimit: d, w, m, y. Defaults to None.
  192. max_results: maximum number of results. Defaults to 10.
  193. page: page of results. Defaults to 1.
  194. backend: A single or comma-delimited backends. Defaults to "auto".
  195. size: Small, Medium, Large, Wallpaper. Defaults to None.
  196. color: color, Monochrome, Red, Orange, Yellow, Green, Blue,
  197. Purple, Pink, Brown, Black, Gray, Teal, White. Defaults to None.
  198. type_image: photo, clipart, gif, transparent, line.
  199. Defaults to None.
  200. layout: Square, Tall, Wide. Defaults to None.
  201. license_image: any (All Creative Commons), Public (PublicDomain),
  202. Share (Free to Share and Use), ShareCommercially (Free to Share and Use Commercially),
  203. Modify (Free to Modify, Share, and Use), ModifyCommercially (Free to Modify, Share, and
  204. Use Commercially). Defaults to None.
  205. Returns:
  206. List of dictionaries with images search results.
  207. """
  208. ```
  209. ***Example***
  210. ```python
  211. results = DDGS().images(
  212. query="butterfly",
  213. region="us-en",
  214. safesearch="off",
  215. timelimit="m",
  216. page=1,
  217. backend="auto",
  218. size=None,
  219. color="Monochrome",
  220. type_image=None,
  221. layout=None,
  222. license_image=None,
  223. )
  224. print(images)
  225. [
  226. {
  227. "title": "File:The Sun by the Atmospheric Imaging Assembly of NASA's Solar ...",
  228. "image": "https://upload.wikimedia.org/wikipedia/commons/b/b4/The_Sun_by_the_Atmospheric_Imaging_Assembly_of_NASA's_Solar_Dynamics_Observatory_-_20100819.jpg",
  229. "thumbnail": "https://tse4.mm.bing.net/th?id=OIP.lNgpqGl16U0ft3rS8TdFcgEsEe&pid=Api",
  230. "url": "https://en.wikipedia.org/wiki/File:The_Sun_by_the_Atmospheric_Imaging_Assembly_of_NASA's_Solar_Dynamics_Observatory_-_20100819.jpg",
  231. "height": 3860,
  232. "width": 4044,
  233. "source": "Bing",
  234. },
  235. ...,
  236. ]
  237. ```
  238. [Go To TOP](#TOP)
  239. ## 3. videos()
  240. ```python
  241. def videos(
  242. query: str,
  243. region: str = "us-en",
  244. safesearch: str = "moderate",
  245. timelimit: str | None = None,
  246. max_results: int | None = 10,
  247. page: int = 1,
  248. backend: str = "auto",
  249. resolution: str | None = None,
  250. duration: str | None = None,
  251. license_videos: str | None = None,
  252. ) -> list[dict[str, str]]:
  253. """DDGS videos metasearch.
  254. Args:
  255. query: videos search query.
  256. region: us-en, uk-en, ru-ru, etc. Defaults to us-en.
  257. safesearch: on, moderate, off. Defaults to "moderate".
  258. timelimit: d, w, m. Defaults to None.
  259. max_results: maximum number of results. Defaults to 10.
  260. page: page of results. Defaults to 1.
  261. backend: A single or comma-delimited backends. Defaults to "auto".
  262. resolution: high, standart. Defaults to None.
  263. duration: short, medium, long. Defaults to None.
  264. license_videos: creativeCommon, youtube. Defaults to None.
  265. Returns:
  266. List of dictionaries with videos search results.
  267. """
  268. ```
  269. ***Example***
  270. ```python
  271. results = DDGS().videos(
  272. query="cars",
  273. region="us-en",
  274. safesearch="off",
  275. timelimit="w",
  276. page=1,
  277. backend="auto",
  278. resolution="high",
  279. duration="medium",
  280. )
  281. print(results)
  282. [
  283. {
  284. "content": "https://www.youtube.com/watch?v=6901-C73P3g",
  285. "description": "Watch the Best Scenes of popular Tamil Serial #Meena that airs on Sun TV. Watch all Sun TV serials immediately after the TV telecast on Sun NXT app. *Free for Indian Users only Download here: Android - http://bit.ly/SunNxtAdroid iOS: India - http://bit.ly/sunNXT Watch on the web - https://www.sunnxt.com/ Two close friends, Chidambaram ...",
  286. "duration": "8:22",
  287. "embed_html": '<iframe width="1280" height="720" src="https://www.youtube.com/embed/6901-C73P3g?autoplay=1" frameborder="0" allowfullscreen></iframe>',
  288. "embed_url": "https://www.youtube.com/embed/6901-C73P3g?autoplay=1",
  289. "image_token": "6c070b5f0e24e5972e360d02ddeb69856202f97718ea6c5d5710e4e472310fa3",
  290. "images": {
  291. "large": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
  292. "medium": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
  293. "motion": "",
  294. "small": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
  295. },
  296. "provider": "Bing",
  297. "published": "2024-07-03T05:30:03.0000000",
  298. "publisher": "YouTube",
  299. "statistics": {"viewCount": 29059},
  300. "title": "Meena - Best Scenes | 02 July 2024 | Tamil Serial | Sun TV",
  301. "uploader": "Sun TV",
  302. },
  303. ...,
  304. ]
  305. ```
  306. [Go To TOP](#TOP)
  307. ## 4. news()
  308. ```python
  309. def news(
  310. query: str,
  311. region: str = "us-en",
  312. safesearch: str = "moderate",
  313. timelimit: str | None = None,
  314. max_results: int | None = 10,
  315. page: int = 1,
  316. backend: str = "auto",
  317. ) -> list[dict[str, str]]:
  318. """DDGS news metasearch.
  319. Args:
  320. query: news search query.
  321. region: us-en, uk-en, ru-ru, etc. Defaults to us-en.
  322. safesearch: on, moderate, off. Defaults to "moderate".
  323. timelimit: d, w, m. Defaults to None.
  324. max_results: maximum number of results. Defaults to 10.
  325. page: page of results. Defaults to 1.
  326. backend: A single or comma-delimited backends. Defaults to "auto".
  327. Returns:
  328. List of dictionaries with news search results.
  329. """
  330. ```
  331. ***Example***
  332. ```python
  333. results = DDGS().news(query="sun", region="us-en", safesearch="off", timelimit="m", page=1, backend="auto")
  334. print(results)
  335. [
  336. {
  337. "date": "2024-07-03T16:25:22+00:00",
  338. "title": "Murdoch's Sun Endorses Starmer's Labour Day Before UK Vote",
  339. "body": "Rupert Murdoch's Sun newspaper endorsed Keir Starmer and his opposition Labour Party to win the UK general election, a dramatic move in the British media landscape that illustrates the country's shifting political sands.",
  340. "url": "https://www.msn.com/en-us/money/other/murdoch-s-sun-endorses-starmer-s-labour-day-before-uk-vote/ar-BB1plQwl",
  341. "image": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/BB1plZil.img?w=2000&h=1333&m=4&q=79",
  342. "source": "Bloomberg on MSN.com",
  343. },
  344. ...,
  345. ]
  346. ```
  347. [Go To TOP](#TOP)
  348. ## 5. books()
  349. ```python
  350. def books(
  351. query: str,
  352. max_results: int | None = 10,
  353. page: int = 1,
  354. backend: str = "auto",
  355. ) -> list[dict[str, str]]:
  356. """DDGS books metasearch.
  357. Args:
  358. query: news search query.
  359. max_results: maximum number of results. Defaults to 10.
  360. page: page of results. Defaults to 1.
  361. backend: A single or comma-delimited backends. Defaults to "auto".
  362. Returns:
  363. List of dictionaries with news search results.
  364. """
  365. ```
  366. ***Example***
  367. ```python
  368. results = DDGS().books(query="sea wolf jack london", page=1, backend="auto")
  369. print(results)
  370. [
  371. {
  372. "title": "The Sea-Wolf",
  373. "author": "Jack London",
  374. "publisher": "DigiCat, 2022",
  375. "info": "English [en], .epub, 🚀/zlib, 0.5MB, 📗 Book (unknown)",
  376. "url": "https://annas-archive.li/md5/574f6556f1df6717de4044e36c7c2782",
  377. "thumbnail": "https://s3proxy.cdn-zlib.sk//covers299/collections/userbooks/da4954486be7c2b2b9f70b2aa5bcf01292de3ea510b5656f892821950ded9ada.jpg",
  378. },
  379. ...,
  380. ]
  381. ```
  382. [Go To TOP](#TOP)
  383. ## 6. extract()
  384. Fetch a URL and extract its content in various formats.
  385. ```python
  386. def extract(
  387. url: str,
  388. fmt: str = "text_markdown",
  389. ) -> dict[str, str | bytes]:
  390. """Fetch a URL and extract its content.
  391. Args:
  392. url: The URL to fetch and extract content from.
  393. fmt: Output format:
  394. "text_markdown" (HTML→Markdown, preserves links/headers/lists),
  395. "text_plain" (HTML→plain text),
  396. "text_rich" (HTML→rich text with headers/lists),
  397. "text" (raw HTML),
  398. "content" (raw bytes).
  399. Returns:
  400. Dictionary with 'url' and 'content' keys.
  401. """
  402. ```
  403. ***Examples***
  404. ```python
  405. # Markdown (default) - preserves links, headers, lists
  406. result = DDGS().extract("https://example.com")
  407. print(result)
  408. {"url": "https://example.com", "content": "# Example Domain\n\nThis domain is for use in..."}
  409. # Plain text
  410. result = DDGS().extract("https://example.com", fmt="text_plain")
  411. # Rich text (headers/lists, no link URLs)
  412. result = DDGS().extract("https://example.com", fmt="text_rich")
  413. # Raw HTML
  414. result = DDGS().extract("https://example.com", fmt="text")
  415. # Raw bytes
  416. result = DDGS().extract("https://example.com", fmt="content")
  417. ```
  418. ***CLI***
  419. ```bash
  420. ddgs extract -u https://example.com
  421. ddgs extract -u https://example.com -f text_plain
  422. ddgs extract -u https://example.com -f content -o output.json
  423. ```
  424. [Go To TOP](#TOP)
  425. ## Disclaimer
  426. This library is for educational purposes only.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.