Python >= 3.8

Duckduckgo_search

使用DuckDuckGo.com搜索引擎搜索单词、文档、图片、视频、新闻、地图和文本翻译。将文件和图片下载到本地硬盘。

安装
命令行版本
Duckduckgo搜索操作符
地区
DDGS和AsyncDDGS类
代理
异常
1. chat() - AI聊天
2. text() - 文本搜索
3. answers() - 即时答案
4. images() - 图片搜索
5. videos() - 视频搜索
6. news() - 新闻搜索
7. maps() - 地图搜索
8. translate() - 翻译
9. suggestions() - 建议
免责声明

安装

pip install -U duckduckgo_search

[!注意] 您可以安装lxml以使用backend='html'或backend='lite'的text函数（大小约12Mb）
pip install -U duckduckgo_search[lxml]

命令行版本

ddgs --help

命令行示例：

# AI聊天
ddgs chat
# 文本搜索
ddgs text -k "standard oil"
# 通过代理查找并下载PDF文件
ddgs text -k "pushkin filetype:pdf" -r wt-wt -m 50 -d -p https://1.2.3.4:1234
# 使用Tor浏览器作为代理（`tb`是`socks5://127.0.0.1:9150`的别名）
ddgs text -k "'to kill a mockingbird' filetype:doc" -m 50 -d -p tb
# 查找并保存为csv
ddgs text -k "'neuroscience exploring the brain' filetype:pdf" -m 70 -o csv
# 查找并下载图片
ddgs images -k "beware of false prophets" -r wt-wt -type photo -m 500 -d
# 获取最近一天的新闻并保存为json
ddgs news -k "sanctions" -m 100 -t d -o json

返回顶部

Duckduckgo搜索操作符

关键词示例	结果
cats dogs	关于猫或狗的结果
"cats and dogs"	精确短语"cats and dogs"的结果。如果没有找到结果，则显示相关结果。
cats -dogs	结果中减少狗的内容
cats +dogs	结果中增加狗的内容
cats filetype:pdf	关于猫的PDF文件。支持的文件类型：pdf、doc(x)、xls(x)、ppt(x)、html
dogs site:example.com	来自example.com的关于狗的页面
cats -site:example.com	关于猫的页面，排除example.com
intitle:dogs	页面标题包含"dogs"一词
inurl:cats	页面URL包含"cats"一词

返回顶部

地区

展开

xa-ar 阿拉伯
xa-en 阿拉伯（英语）
ar-es 阿根廷
au-en 澳大利亚
at-de 奥地利
be-fr 比利时（法语）
be-nl 比利时（荷兰语）
br-pt 巴西
bg-bg 保加利亚
ca-en 加拿大
ca-fr 加拿大（法语）
ct-ca 加泰罗尼亚
cl-es 智利
cn-zh 中国
co-es 哥伦比亚
hr-hr 克罗地亚
cz-cs 捷克共和国
dk-da 丹麦
ee-et 爱沙尼亚
fi-fi 芬兰
fr-fr 法国
de-de 德国
gr-el 希腊
hk-tzh 香港
hu-hu 匈牙利
in-en 印度
id-id 印度尼西亚
id-en 印度尼西亚（英语）
ie-en 爱尔兰
il-he 以色列
it-it 意大利
jp-jp 日本
kr-kr 韩国
lv-lv 拉脱维亚
lt-lt 立陶宛
xl-es 拉丁美洲
my-ms 马来西亚
my-en 马来西亚（英语）
mx-es 墨西哥
nl-nl 荷兰
nz-en 新西兰
no-no 挪威
pe-es 秘鲁
ph-en 菲律宾
ph-tl 菲律宾（他加禄语）
pl-pl 波兰
pt-pt 葡萄牙
ro-ro 罗马尼亚
ru-ru 俄罗斯
sg-en 新加坡
sk-sk 斯洛伐克共和国
sl-sl 斯洛文尼亚
za-en 南非
es-es 西班牙
se-sv 瑞典
ch-de 瑞士（德语）
ch-fr 瑞士（法语）
ch-it 瑞士（意大利语）
tw-tzh 台湾
th-th 泰国
tr-tr 土耳其
ua-uk 乌克兰
uk-en 英国
us-en 美国
ue-es 美国（西班牙语）
ve-es 委内瑞拉
vn-vi 越南
wt-wt 无地区

返回顶部

DDGS和AsyncDDGS类

DDGS和AsyncDDGS类用于从DuckDuckGo.com获取搜索结果。要使用AsyncDDGS类，您可以使用Python的asyncio库执行异步操作。要初始化DDGS或AsyncDDGS类的实例，您可以提供以下可选参数：

class DDGS:
    """DuckDuckgo_search类，用于从duckduckgo.com获取搜索结果

    参数：
        headers (dict, 可选)：HTTP客户端的头部字典。默认为None。
        proxy (str, 可选)：HTTP客户端的代理，支持http/https/socks5协议。
            示例："http://user:pass@example.com:3128"。默认为None。
        timeout (int, 可选)：HTTP客户端的超时值。默认为10。
    """

以下是初始化DDGS类的示例。

from duckduckgo_search import DDGS
results = DDGS().text("python编程", max_results=5)
print(results)

以下是初始化AsyncDDGS类的示例：

import asyncio

from duckduckgo_search import AsyncDDGS

async def aget_results(word):
    results = await AsyncDDGS(proxy=None).atext(word, max_results=100)
    return results

async def main():
    words = ["太阳", "地球", "月亮"]
    tasks = [aget_results(w) for w in words]
    results = await asyncio.gather(*tasks)
    print(results)

if __name__ == "__main__":
    asyncio.run(main())

返回顶部

代理

包支持http/https/socks代理。示例：http://user:pass@example.com:3128。使用轮换代理。否则，每次初始化DDGS或AsyncDDGS时使用新的代理。

1. 最简单的方法。启动Tor浏览器

ddgs = DDGS(proxy="tb", timeout=20)  # "tb"是"socks5://127.0.0.1:9150"的别名
results = ddgs.text("你需要的内容", max_results=50)

2. 使用任何代理服务器 (示例使用iproyal轮换住宅代理)

ddgs = DDGS(proxy="socks5://user:password@geo.iproyal.com:32325", timeout=20)
results = ddgs.text("你需要的内容", max_results=50)

返回顶部

异常

异常：

DuckDuckGoSearchException：duckduckgo_search错误的基本异常。
RatelimitException：继承自DuckDuckGoSearchException，在超过API请求速率限制时抛出。
TimeoutException：继承自DuckDuckGoSearchException，在API请求超时时抛出。

返回顶部

1. chat() - AI聊天

def chat(self, keywords: str, model: str = "gpt-4o-mini", timeout: int = 30) -> str:
    """启动与DuckDuckGo AI的聊天会话。

    参数：
        keywords (str): 发送给AI的初始消息或问题。
        model (str): 要使用的模型："gpt-4o-mini"、"claude-3-haiku"、"llama-3.1-70b"、"mixtral-8x7b"。
            默认为"gpt-4o-mini"。
        timeout (int): HTTP客户端的超时值。默认为30。

    返回：
        str: AI的回复。
    """

示例

results = DDGS().chat("总结丹尼尔·笛福的《巩固者》", model='claude-3-haiku')

# 异步
results = await AsyncDDGS().achat('描述人类作为物种的特征习惯和行为')

返回顶部

2. text() - duckduckgo.com的文本搜索

def text(
    keywords: str,
    region: str = "wt-wt",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    backend: str = "api",
    max_results: int | None = None,
) -> list[dict[str, str]]:
    """DuckDuckGo文本搜索生成器。查询参数：https://duckduckgo.com/params。

    参数：
        keywords: 查询关键词。
        region: wt-wt、us-en、uk-en、ru-ru等。默认为"wt-wt"。
        safesearch: on、moderate、off。默认为"moderate"。
        timelimit: d、w、m、y。默认为None。
        backend: api、html、lite。默认为api。
            api - 从https://duckduckgo.com收集数据，
            html - 从https://html.duckduckgo.com收集数据，
            lite - 从https://lite.duckduckgo.com收集数据。
        max_results: 最大结果数。如果为None，仅返回第一个响应的结果。默认为None。

    返回：
        包含搜索结果的字典列表。
    """

示例

results = DDGS().text('自由生存或死亡', region='wt-wt', safesearch='off', timelimit='y', max_results=10)
# 搜索pdf文件
results = DDGS().text('俄罗斯 filetype:pdf', region='wt-wt', safesearch='off', timelimit='y', max_results=10)

# 异步
results = await AsyncDDGS().atext('太阳', region='wt-wt', safesearch='off', timelimit='y', max_results=10)
print(results)
[
    {
        "title": "新闻、体育、名人和娱乐 | 太阳报",
        "href": "https://www.thesun.co.uk/",
        "body": "获取来自太阳报的最新新闻、独家报道、体育、名人、娱乐、政治、商业和生活方式",
    }, ...
]

返回顶部

3. answers() - duckduckgo.com的即时回答

def answers(keywords: str) -> list[dict[str, str]]:
    """DuckDuckGo即时回答。查询参数：https://duckduckgo.com/params。
    
    参数：
        keywords: 查询关键词，
    
    返回：
        包含即时回答结果的字典列表。
    """

示例

results = DDGS().answers("太阳")

# 异步
results = await AsyncDDGS().aanswers("太阳")
print(results)
[
    {
        "icon": None,
        "text": "太阳是太阳系中心的恒星。它是一个巨大的、几乎完美的热等离子体球体，其核心通过核聚变反应加热到白热化状态，主要以可见光和红外辐射的形式从其表面辐射能量，其中10%为紫外能量。它是地球上生命最重要的能量来源。太阳在许多文化中一直是崇拜的对象。自古以来，它一直是天文研究的核心主题。太阳以24,000到28,000光年的距离绕银河系中心运行。从地球来看，它距离1个天文单位或约8光分钟。它的直径约为1,391,400公里，是地球的109倍。它的质量约为地球的330,000倍，占太阳系总质量的99.86%。太阳的质量大约四分之三是氢；其余主要是氦，还有少量更重的元素，包括氧、碳、氖和铁。",
        "topic": None,
        "url": "https://zh.wikipedia.org/wiki/太阳",
    }, ...
]

返回顶部

4. images() - duckduckgo.com的图片搜索

def images(
    keywords: str,
    region: str = "wt-wt",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    size: str | None = None,
    color: str | None = None,
    type_image: str | None = None,
    layout: str | None = None,
    license_image: str | None = None,
    max_results: int | None = None,
) -> list[dict[str, str]]:
    """DuckDuckGo图片搜索。查询参数：https://duckduckgo.com/params。
    
    参数：
        keywords: 查询关键词。
        region: wt-wt、us-en、uk-en、ru-ru等。默认为"wt-wt"。
        safesearch: on、moderate、off。默认为"moderate"。
        timelimit: Day、Week、Month、Year。默认为None。
        size: Small、Medium、Large、Wallpaper。默认为None。
        color: color、Monochrome、Red、Orange、Yellow、Green、Blue、
            Purple、Pink、Brown、Black、Gray、Teal、White。默认为None。
        type_image: photo、clipart、gif、transparent、line。
            默认为None。
        layout: Square、Tall、Wide。默认为None。
        license_image: any（所有创意共享）、Public（公共领域）、
            Share（可自由分享和使用）、ShareCommercially（可自由分享和商业使用）、
            Modify（可自由修改、分享和使用）、ModifyCommercially（可自由修改、分享和
            商业使用）。默认为None。
        max_results: 最大结果数。如果为None，则仅返回第一个响应的结果。默认为None。
    
    返回：
        包含图片搜索结果的字典列表。
    """

示例

results = DDGS().images(
    keywords="butterfly",
    region="wt-wt",
    safesearch="off",
    size=None,
    color="Monochrome",
    type_image=None,
    layout=None,
    license_image=None,
    max_results=100,
)

# 异步
results = await AsyncDDGS().aimages('sun', region='wt-wt', safesearch='off', max_results=20)
print(images)
[
    {
        "title": "文件:NASA太阳动力学天文台大气成像装置拍摄的太阳 ...",
        "image": "https://upload.wikimedia.org/wikipedia/commons/b/b4/The_Sun_by_the_Atmospheric_Imaging_Assembly_of_NASA's_Solar_Dynamics_Observatory_-_20100819.jpg",
        "thumbnail": "https://tse4.mm.bing.net/th?id=OIP.lNgpqGl16U0ft3rS8TdFcgEsEe&pid=Api",
        "url": "https://en.wikipedia.org/wiki/File:The_Sun_by_the_Atmospheric_Imaging_Assembly_of_NASA's_Solar_Dynamics_Observatory_-_20100819.jpg",
        "height": 3860,
        "width": 4044,
        "source": "Bing",
    }, ...
]

返回顶部

5. videos() - duckduckgo.com的视频搜索

def videos(
    keywords: str,
    region: str = "wt-wt",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    resolution: str | None = None,
    duration: str | None = None,
    license_videos: str | None = None,
    max_results: int | None = None,
) -> list[dict[str, str]]:
    """DuckDuckGo视频搜索。查询参数：https://duckduckgo.com/params。
    
    参数：
        keywords: 查询关键词。
        region: wt-wt、us-en、uk-en、ru-ru等。默认为"wt-wt"。
        safesearch: on、moderate、off。默认为"moderate"。
        timelimit: d、w、m。默认为None。
        resolution: high、standart。默认为None。
        duration: short、medium、long。默认为None。
        license_videos: creativeCommon、youtube。默认为None。
        max_results: 最大结果数。如果为None，则仅返回第一个响应的结果。默认为None。
    
    返回：
        包含视频搜索结果的字典列表。
    """

示例

results = DDGS().videos(
    keywords="cars",
    region="wt-wt",
    safesearch="off",
    timelimit="w",
    resolution="high",
    duration="medium",
    max_results=100,
)

# 异步
results = await AsyncDDGS().avideos('sun', region='wt-wt', safesearch='off', timelimit='y', max_results=10)
print(results)
[
    {
        "content": "https://www.youtube.com/watch?v=6901-C73P3g",
        "description": "观看在Sun TV播出的热门泰米尔连续剧#Meena的精彩片段。所有Sun TV连续剧在电视播出后立即可在Sun NXT应用程序上观看。*仅对印度用户免费 下载地址：Android - http://bit.ly/SunNxtAdroid iOS：印度 - http://bit.ly/sunNXT 网页观看 - https://www.sunnxt.com/ 两个亲密的朋友，Chidambaram ...",
        "duration": "8:22",
        "embed_html": '<iframe width="1280" height="720" src="https://www.youtube.com/embed/6901-C73P3g?autoplay=1" frameborder="0" allowfullscreen></iframe>',
        "embed_url": "https://www.youtube.com/embed/6901-C73P3g?autoplay=1",
        "image_token": "6c070b5f0e24e5972e360d02ddeb69856202f97718ea6c5d5710e4e472310fa3",
        "images": {
            "large": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
            "medium": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
            "motion": "",
            "small": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
        },
        "provider": "Bing",
        "published": "2024-07-03T05:30:03.0000000",
        "publisher": "YouTube",
        "statistics": {"viewCount": 29059},
        "title": "Meena - 精彩片段 | 2024年7月2日 | 泰米尔连续剧 | Sun TV",
        "uploader": "Sun TV",
    }, ...
]

返回顶部

6. news() - duckduckgo.com的新闻搜索

def news(
    keywords: str,
    region: str = "wt-wt",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = None,
) -> list[dict[str, str]]:
    """DuckDuckGo新闻搜索。查询参数：https://duckduckgo.com/params。
    
    参数：
        keywords: 查询关键词。
        region: wt-wt、us-en、uk-en、ru-ru等。默认为"wt-wt"。
        safesearch: on、moderate、off。默认为"moderate"。
        timelimit: d、w、m。默认为None。
        max_results: 最大结果数。如果为None，则仅返回第一个响应的结果。默认为None。
    
    返回：
        包含新闻搜索结果的字典列表。
    """

示例

results = DDGS().news(keywords="sun", region="wt-wt", safesearch="off", timelimit="m", max_results=20)

# 异步
results = await AsyncDDGS().anews('sun', region='wt-wt', safesearch='off', timelimit='d', max_results=10)
print(results)
[
    {
        "date": "2024-07-03T16:25:22+00:00",
        "title": "默多克的太阳报在英国大选前一天支持工党领袖斯塔默",
        "body": "鲁珀特·默多克的太阳报支持基尔·斯塔默和他的反对党工党赢得英国大选，这是英国媒体格局中的一个戏剧性变化，反映了该国不断变化的政治局势。",
        "url": "https://www.msn.com/en-us/money/other/murdoch-s-sun-endorses-starmer-s-labour-day-before-uk-vote/ar-BB1plQwl",
        "image": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/BB1plZil.img?w=2000&h=1333&m=4&q=79",
        "source": "Bloomberg on MSN.com",
    }, ...
]

返回顶部

7. maps() - duckduckgo.com地图搜索

def maps(
    keywords,
    place: str | None = None,
    street: str | None = None,
    city: str | None = None,
    county: str | None = None,
    state: str | None = None,
    country: str | None = None,
    postalcode: str | None = None,
    latitude: str | None = None,
    longitude: str | None = None,
    radius: int = 0,
    max_results: int | None = None,
) -> list[dict[str, str]]:
    """DuckDuckGo地图搜索。查询参数：https://duckduckgo.com/params。
    
    参数：
        keywords: 查询关键词
        place: 如果设置，其他参数将不被使用。默认为None。
        street: 门牌号/街道。默认为None。
        city: 搜索城市。默认为None。
        county: 搜索县。默认为None。
        state: 搜索州。默认为None。
        country: 搜索国家。默认为None。
        postalcode: 搜索邮政编码。默认为None。
        latitude: 地理坐标（南北位置）。默认为None。
        longitude: 地理坐标（东西位置）；如果设置了经纬度，其他参数将不被使用。默认为None。
        radius: 按公里扩大搜索范围。默认为0。
        max_results: 最大结果数。如果为None，则仅返回第一个响应的结果。默认为None。
    
    返回：
        包含地图搜索结果的字典列表。
    """

示例

results = DDGS().maps("school", place="Uganda", max_results=50)

# 异步
results = await AsyncDDGS().amaps('shop', place="Baltimor", max_results=10)
print(results)
[
    {
        "title": "The Bun Shop",
        "address": "239 W Read St, Baltimore, MD 21201-4845",
        "country_code": None,
        "url": "https://www.facebook.com/TheBunShop/",
        "phone": "+14109892033",
        "latitude": 39.3006042,
        "longitude": -76.6195788,
        "source": "https://www.tripadvisor.com/Restaurant_Review-g60811-d4819859-Reviews-The_Bun_Shop-Baltimore_Maryland.html?m=63959",
        "image": "",
        "desc": "",
        "hours": {
            "Fri": "07:00:00–03:00:00",
            "Mon": "07:00:00–03:00:00",
            "Sat": "07:00:00–03:00:00",
            "Sun": "07:00:00–03:00:00",
            "Thu": "07:00:00–03:00:00",
            "Tue": "07:00:00–03:00:00",
            "Wed": "07:00:00–03:00:00",
            "closes_soon": 0,
            "is_open": 1,
            "opens_soon": 0,
            "state_switch_time": "03:00",
        },
        "category": "Cafe",
        "facebook": "",
        "instagram": "",
        "twitter": "",
    }, ...
]

返回顶部

8. translate() - duckduckgo.com翻译

def translate(
    self,
    keywords: str,
    from_: str | None = None,
    to: str = "en",
) -> list[dict[str, str]]:
    """DuckDuckGo翻译。
    
    参数：
        keywords: 要翻译的字符串或字符串列表。
        from_: 从哪种语言翻译（默认自动检测）。默认为None。
        to: 翻译成哪种语言。默认为"en"。
    
    返回：
        包含已翻译关键词的字典列表。
    """

示例

keywords = 'school'
# 也可以是
keywords = ['school', 'cat']
results = DDGS().translate(keywords, to="de")

# 异步
results = await AsyncDDGS().atranslate('sun', to="de")
print(results)
[{"detected_language": "en", "translated": "Sonne", "original": "sun"}]

返回顶部

9. suggestions() - duckduckgo.com建议

def suggestions(
    keywords,
    region: str = "wt-wt",
) -> list[dict[str, str]]:
    """DuckDuckGo建议。查询参数：https://duckduckgo.com/params。
    
    参数：
        keywords: 查询关键词。
        region: wt-wt、us-en、uk-en、ru-ru等。默认为"wt-wt"。
    
    返回：
        包含建议结果的字典列表。
    """

示例

results = DDGS().suggestions("fly")

# 异步
results = await AsyncDDGS().asuggestions('sun')
print(results)
[
    {"phrase": "sunshine live"},
    {"phrase": "sunexpress"},
    {"phrase": "sunday natural"},
    {"phrase": "sunrise village spiel"},
    {"phrase": "sunny portal"},
    {"phrase": "sundair"},
    {"phrase": "sunny cars"},
    {"phrase": "sunexpress online check-in"},
]