DuckDuckGo API: A Developer's Guide for 2026

As the most popular privacy-focused search engine, DuckDuckGo is sought after by developers wanting to access its search results programmatically. Unfortunately, the documentation for the official Instant Answer API is sparse, and you may be left to rely on guesswork or unofficial approaches.

Accessing full DuckDuckGo search results programmatically might require accessing the HTML endpoints directly or using the ddgs Python Package. Neither of them is officially allowed, so consider the possible restrictions, including legal consequences, depending on your use of Duck Duck Go API data.

Introduction to the DuckDuckGo API Landscape

Developers look into DuckDuckGo’s libraries and API because it solves common problems with other search APIs. DuckDuckGo allows you to build search into your application or data pipeline without the privacy and data-leakage baggage of traditional search engines like Google.

The results are less biased and personalized, which is important for many use cases. Since there’s less data gathered about the user, it’s also considered better for compliance with data protection regulations like GDPR and CCPA.

Additionally, Google’s API , at least the official one, is free only up to 100 queries per day, while the methods to access DuckDuckGo results are free. Scraping Google results is also more difficult, as their bot detection is notoriously aggressive when it comes to limiting access to their Search Engine Results Page (SERP).

There are three primary ways developers use DuckDuckGo’s search results programmatically.

• Instant Answers API is DuckDuckGo’s only official API. It returns structured, factual snippets, such as definitions, Wikipedia abstracts, and similar, for well-known queries. It’s not SERP data, but the access is free, and no API key is required.
• HTML endpoints, such as http://html.duckduckgo.com and lite.duckduckgo.com, are an unofficial way to access the DuckDuckGo SERP. You can send HTTP requests directly and parse the returned HTML yourself. Requires maintaining your own parser and handling various restrictions.
• The ddgs Python package is an unofficial, open-source library that handles HTML endpoint scraping for you. It’s convenient since you don’t need manual parsing, but you become dependent on the developers’ fixes when DuckDuckGo changes its structure.

Official DuckDuckGo Instant Answer API

Instant Answer API , the only officially supported API for DuckDuckGo, is a free public service allowing developers to integrate concise, specialized answers directly into their applications. It helps to easily source topic summaries, definitions, quick facts, Wikipedia summaries, unit conversions, and similar zero-click results.

Its endpoint is https://api.duckduckgo.com/ but there’s a lack of official sources with a well-documented query format. Through trial and error, community users have developed working implementations in various formats. The one below is a good start for testing, but it will likely require modifications depending on your use case.

https://api.duckduckgo.com/?q={query}&format=json&t=nameofapp

It returns fields like Abstract, AbstractText, AbstractURL, RelatedTopics, Answer, and Type in machine-readable JSON. The best part is that no authentication or API key is required.

The main limitation is that Instant Answers is not a full search API. It will only cover well-known entities or facts, and most deep queries (non-topic names) will return blank. Actual SERP data requires a different approach entirely.

HTML Endpoint for DuckDuckGo Search Results

For full SERP-style results, developers must turn to DuckDuckGo HTML endpoints - html.duckduckgo.com/html/ and lite.duckduckgo.com/lite/. They both accept HTTP POST requests. While the HTML endpoint returns fuller results, the lite version is easier to parse. For region and language-specific results, append the specific locale.

https://html.duckduckgo.com/html/&kl=de-de
lite.duckduckgo.com/lite/&kl=fr-fr

You'll also need to use BeautifulSoup to parse the collected data, as the returned items are raw HTML. If data from more than one page is collected, you'll need to insert *vdq *tokens with each request. It's a version query data token that DuckDuckGo generates on the server-side and embeds in the HTML of the first response.

It's tied to your specific query and session context, and must be inserted into each subsequent request. Without the vdq token, DuckDuckGo will either return the first page again or block your requests entirely. Automating requires some advanced Python programming, so many developers prefer to use the ddgs library instead.

Using the ddgs Python Package (Formerly duckduckgo_search)

Compared to coding your own DuckDuckGo scraper, the ddgs Python Package is much more straightforward to use. It can be installed with a pip command in your terminal.

pip install -U ddgs

A basic text search query in a Python script follows a simple format.

from ddgs import DDGS
results = DDGS().text("your query", max_results=10)
print(results)

Search queries can be supplemented with region, timelimit, max_results, and other parameters. Special queries, such as image, video, news, and books searches, have various unique parameters. The ddgs Python library is a powerful wrapper that can help you deal with common issues scraping DuckDuckGo, but it's not an official API and is vulnerable to site changes.

CLI Usage and Automation Workflows

The ddgs package can be used in command-line tools, but it's not a search tool in a traditional sense. Normally, search results APIs send requests directly to the search engine, in this case, DuckDuckGo. The newest version of the ddgs package can start a small web server on your own machine, which acts as an intermediary.

This is required due to the Model Context Protocol (MCP) used by AI tools, which simplifies how they connect to external data sources. It also centralizes proxy and rate limit settings. Besides the optional deployment of the server, the CLI commands are quite straightforward:

• api - start/stop the DDGS API server.
• books - CLI function to perform a DDGS books metasearch.
• extract - CLI function to extract content from a URL.
• images - CLI function to perform a DDGS images metasearch.
• mcp - Start DDGS MCP server over stdio for local MCP clients.
• news - CLI function to perform a DDGS news metasearch.
• text - CLI function to perform a DDGS text metasearch.
• version - Print and return version.
• videos - CLI function to perform a DDGS videos metasearch.

Proxies, Rate Limiting, and Error Handling

Unless you're collecting data on a one-time basis, proxies are necessary. Any meaningful scale of data collection with the DDG library or a custom DuckDuckGo scraper requires them. Rotating residential proxies are typically best for such tasks, as other proxies tend to get flagged faster.

In ddgs, you can set up proxies via the proxy parameter, while for custom scrapers, rotating the IP address for each request is recommended. Yet, proxies alone will not ensure the success of your scraping efforts.

While there's no official threshold published, it's best to start with fewer than 30 requests per minute per IP address. Such a best practice is a good start, but you'll still need to add randomized delays between requests and test different fingerprints when using a custom scraper.

These strategies will help you to minimize failures, but some errors are unavoidable. Be prepared to handle the most common errors and their fallbacks when scraping DuckDuckGo.

• RatelimitException happens when the site wants to signal to you that you're sending too many requests. Back off and add a randomized delay, rotate the proxy server before retrying.
• DuckDuckGoSearchException is the ddg libraries' general catch-all for anything unexpected. Error message typically specifies the issue, but it's often related to network or parsing failures due to a changed HTML structure.
• 202 responses are a soft rate limit signaling that DuckDuckGo received your request but won't respond. Treat it the same as RatelimitException.
• A 403 response indicates that the server won't respond due to insufficient permissions. In this case, it often means your IP address is flagged. Rotate your proxy and adjust the delay to fix it.
• vqd token extraction failures can be noticed from failed pagination while using custom scrapers. Re-fetch the first page, extract the new vqd token, and try again.

Legal, Ethical, and Branding Considerations

If you're using the official API, the only requirements from DuckDuckGo are to identify your app in the &t=nameofapp, attribute results with their logo, and get email approval before any commercial use. Unlike Microsoft or Google, DuckDuckGo is known to at least answer emails asking for approval.

It's important to know that DuckDuckGo actively fights against automated requests using its HTML endpoints. Expect rate limits and restrictions in the form of 202, 403, and similar errors. Even if collecting publicly available data is legal, scraping endpoints violates the terms of DuckDuckGo and potentially worsens the service for other users.

The same reservations apply to using the ddgs Python library. So, before implementing any integration with these tools, test it at low volumes, follow known rules, and have a fallback solution ready in case the solution no longer works.

Conclusion

None of the methods to scrape DuckDuckGo search results is perfect. Yet, DuckDuckGo has some unique benefits, and accessing data might be easier compared to similar alternatives. Scraping DuckDuckGo is definitely worth a try and works with specialized proxy servers for the task.

FAQ