bug-ops/zeph/web-search

Web Search via DuckDuckGo Instant Answer API

Endpoint

GET https://api.duckduckgo.com/?q=QUERY&format=json&no_html=1&skip_disambig=1

Step-by-Step Instructions

1. Take the user's query and convert it into effective search terms
2. URL-encode the query (spaces become +, special characters percent-encoded)
3. Execute the curl command below
4. Parse the JSON response to find the best answer
5. Summarize the results for the user in natural language
6. Always cite the source URL from the response

Quick Search

curl -s "https://api.duckduckgo.com/?q=QUERY&format=json&no_html=1&skip_disambig=1" | jq '{
  type: .Type,
  abstract: .AbstractText,
  abstract_source: .AbstractSource,
  abstract_url: .AbstractURL,
  answer: .Answer,
  definition: .Definition,
  definition_source: .DefinitionSource,
  redirect: .Redirect,
  related: [.RelatedTopics[:5][] | select(.Text) | {text: .Text, url: .FirstURL}]
}'

Compact Search (Best Single Answer)

curl -s "https://api.duckduckgo.com/?q=QUERY&format=json&no_html=1&skip_disambig=1" | jq -r '
  if .Redirect != "" then "Redirect: " + .Redirect
  elif .Answer != "" then .Answer
  elif .AbstractText != "" then .AbstractText + "\nSource: " + .AbstractURL
  elif .Definition != "" then .Definition + "\nSource: " + .DefinitionURL
  elif (.RelatedTopics | length) > 0 then .RelatedTopics[0].Text + "\nURL: " + .RelatedTopics[0].FirstURL
  else "No results found. Try different keywords."
  end'

Detailed Results (All Fields)

curl -s "https://api.duckduckgo.com/?q=QUERY&format=json&no_html=1&skip_disambig=1" | jq '{
  type: .Type,
  heading: .Heading,
  abstract: .AbstractText,
  abstract_source: .AbstractSource,
  abstract_url: .AbstractURL,
  answer: .Answer,
  answer_type: .AnswerType,
  definition: .Definition,
  definition_source: .DefinitionSource,
  definition_url: .DefinitionURL,
  image: .Image,
  redirect: .Redirect,
  related: [.RelatedTopics[]? | select(.Text) | {text: .Text, url: .FirstURL, icon: .Icon.URL}],
  results: [.Results[]? | {text: .Text, url: .FirstURL}],
  infobox: .Infobox
}'

Query Parameters

Response Fields

Primary Answer Fields

Definition Fields

Related and Redirect

RelatedTopics Object

Each item in RelatedTopics contains:

When Type is D (disambiguation), RelatedTopics may contain grouped items with a Name key and nested Topics array.

Search Strategies

Strategy 1: Direct Query

Use the user's question directly as the query.

# "What is Rust programming language?"
curl -s "https://api.duckduckgo.com/?q=Rust+programming+language&format=json&no_html=1&skip_disambig=1"

Strategy 2: Keyword Extraction

Extract key nouns and concepts, drop filler words.

# "Can you tell me about the history of the Internet?" -> "history Internet"
curl -s "https://api.duckduckgo.com/?q=history+of+the+Internet&format=json&no_html=1&skip_disambig=1"

Strategy 3: Specific Entity Lookup

For people, places, or things, use the proper name.

# "Who created Linux?"
curl -s "https://api.duckduckgo.com/?q=Linus+Torvalds&format=json&no_html=1&skip_disambig=1"

Strategy 4: Fallback Rephrasing

If the first query returns empty fields, try rephrasing:

• Add context words: "Python" -> "Python programming language"
• Use the full proper name: "JS" -> "JavaScript"
• Try a definition query: "define quantum computing"
• Remove overly specific terms and broaden the search

Parsing the Response

Priority Order for Extracting the Best Answer

1. Redirect — if non-empty, the query is a !bang command; follow the URL
2. Answer — instant answers (calculations, IP lookups, conversions) are the most direct
3. AbstractText — topic summaries from sources like Wikipedia
4. Definition — dictionary definitions
5. RelatedTopics[0].Text — first related topic as a fallback
6. If all are empty, rephrase and retry with different keywords

Extracting Structured Data from Infobox

curl -s "https://api.duckduckgo.com/?q=Albert+Einstein&format=json&no_html=1" | jq '.Infobox.content[]? | {label: .label, value: .value}'

URL Encoding Rules

In bash, use jq -rn --arg q "search terms" '$q | @uri' for proper encoding.

Important Notes

• The DuckDuckGo API returns instant answers, not web search results. It excels at factual lookups, definitions, and entity information, but may return empty for very recent events or niche topics
• Always use format=json for machine-readable output
• Always use no_html=1 to get clean text without HTML tags
• Use skip_disambig=1 to get direct answers instead of disambiguation pages
• Always cite the source URL (AbstractURL, DefinitionURL, or FirstURL) when presenting results
• The API is free and does not require authentication
• Rate limiting: be respectful; do not send rapid-fire requests. A brief pause between retries is courteous
• If the API returns no useful data after 2 attempts with different phrasings, inform the user that the information could not be found via this source
• The Redirect field handles DuckDuckGo !bang shortcuts (e.g., !w for Wikipedia, !so for StackOverflow)