# DuckDuckGo Engines — SearXNG Documentation (2024.5.4+dbed8da28)

# DuckDuckGo Engines

## DuckDuckGo Lite

searx.engines.duckduckgo.cache_vqd(query, value)

  Caches a `vqd` value from a query.

searx.engines.duckduckgo.fetch_traits(engine_traits: EngineTraits )

  Fetch languages & regions from DuckDuckGo.

  SearXNG’s `all` locale maps DuckDuckGo’s “Alle regions” (`wt-wt`). DuckDuckGo’s language “Browsers prefered language” (`wt_WT`) makes no sense in a SearXNG request since SearXNG’s `all` will not add a `Accept-Language` HTTP header. The value in `engine_traits.all_locale` is `wt-wt` (the region).

  Beside regions DuckDuckGo also defines its languages by region codes. By example these are the english languages in DuckDuckGo:

  - en_US

  - en_AU

  - en_CA

  - en_GB

  The function `get_ddg_lang` evaluates DuckDuckGo’s language from SearXNG’s locale.

searx.engines.duckduckgo.get_ddg_lang(eng_traits: EngineTraits, sxng_locale, default='en_US')

  Get DuckDuckGo’s language identifier from SearXNG’s locale.

  DuckDuckGo defines its languages by region codes (see `fetch_traits`).

  To get region and language of a DDG service use:

  It might confuse, but the `l` value of the cookie is what SearXNG calls the region:

      # !ddi paris :es-AR --> {'ad': 'es_AR', 'ah': 'ar-es', 'l': 'ar-es'}
      params['cookies']['ad'] = eng_lang
      params['cookies']['ah'] = eng_region
      params['cookies']['l'] = eng_region

  Hint

  DDG-lite does not offer a language selection to the user, only a region can be selected by the user (`eng_region` from the example above). DDG-lite stores the selected region in a cookie:

      params['cookies']['kl'] = eng_region  # 'ar-es'

searx.engines.duckduckgo.get_vqd(query)

  Returns the `vqd` that fits to the query. If there is no `vqd` cached (`cache_vqd`) the query is sent to DDG to get a vqd value from the response.

  Hint

  If an empty string is returned there are no results for the `query` and therefore no `vqd` value.

  DDG’s bot detection is sensitive to the `vqd` value. For some search terms (such as extremely long search terms that are often sent by bots), no `vqd` value can be determined.

  If SearXNG cannot determine a `vqd` value, then no request should go out to DDG:

  > A request with a wrong `vqd` value leads to DDG temporarily putting SearXNG’s IP on a block list.

  > Requests from IPs in this block list run into timeouts.

  Not sure, but it seems the block list is a sliding window: to get my IP rid from the bot list I had to cool down my IP for 1h (send no requests from that IP to DDG).

  TL;DR; the `vqd` value is needed to pass DDG’s bot protection and is used by all request to DDG:

  - DuckDuckGo Lite: `https://lite.duckduckgo.com/lite` (POST form data)

  - DuckDuckGo Web: `https://links.duckduckgo.com/d.js?q=...&vqd=...`

  - DuckDuckGo Images: `https://duckduckgo.com/i.js??q=...&vqd=...`

  - DuckDuckGo Videos: `https://duckduckgo.com/v.js??q=...&vqd=...`

  - DuckDuckGo News: `https://duckduckgo.com/news.js??q=...&vqd=...`

searx.engines.duckduckgo.send_accept_language_header = True

  DuckDuckGo-Lite tries to guess user’s prefered language from the HTTP `Accept-Language`. Optional the user can select a region filter (but not a language).

## DuckDuckGo Extra (images, videos, news)

searx.engines.duckduckgo_extra.ddg_category = 'images'

  The category must be any of `images`, `videos` and `news`

## DuckDuckGo Instant Answer API

The DDG-API is no longer documented but from reverse engineering we can see that some services (e.g. instant answers) still in use from the DDG search engine.

As far we can say the instant answers API does not support languages, or at least we could not find out how language support should work. It seems that most of the features are based on English terms.

searx.engines.duckduckgo_definitions.area_to_str(area)

  parse `{'unit': 'https://www.wikidata.org/entity/Q712226', 'amount': '+20.99'}`

searx.engines.duckduckgo_definitions.is_broken_text(text)

  duckduckgo may return something like `<a href="xxxx">http://somewhere Related website<a/>`

  The href URL is broken, the “Related website” may contains some HTML.

  The best solution seems to ignore these results.

## DuckDuckGo Weather