DuckDuckGo Instant Answer API for Crystal

A Crystal library for the DuckDuckGo Instant Answer API. Get topic summaries, definitions, instant answers, and more.

Features

• Topic Summaries: Wikipedia-style abstracts for well-known topics
• Definitions: Dictionary definitions from various sources
• Disambiguation: Handle queries with multiple meanings
• !Bang Redirects: Support for !bang commands
• Instant Answers: Calculations, conversions, IP lookups, etc.
• Type Safety: Fully typed response objects and enums
• Testable: Includes HTTP adapter pattern for easy mocking

Installation

Add the dependency to your shard.yml:

dependencies:
  duckduckgo:
    github: amscotti/duckduckgo

Then run shards install

Quick Start

require "duckduckgo"

# Simplest: get the best answer in one line
puts DuckDuckGo.zci("Crystal programming language")
# => "Crystal is a general-purpose, object-oriented programming language..."

# Full query for more control
result = DuckDuckGo.query("Crystal programming language")
puts result.heading        # => "Crystal (programming language)"
puts result.abstract_text  # => "Crystal is a general-purpose..."
puts result.abstract_source # => "Wikipedia"

# Instant answers
puts DuckDuckGo.zci("what is my ip")  # => "Your IP address is..."

# !Bang redirects
result = DuckDuckGo.query("!imdb the matrix", no_redirect: true)
puts result.redirect  # => "https://www.imdb.com/find?q=the%20matrix"

Handling Response Types

The API returns different types of responses based on the query:

result = DuckDuckGo.query("apple")

case result.type
when .article?
  # Topic with abstract (e.g., "Crystal programming language")
  puts result.abstract_text
when .disambiguation?
  # Multiple meanings (e.g., "apple" -> fruit, company, etc.)
  result.flat_related_topics.each { |topic| puts topic.text }
when .category?
  # List of items (e.g., "simpsons characters")
  result.flat_related_topics.each { |topic| puts topic.text }
when .exclusive?
  # Instant answer only (e.g., calculations)
  puts result.answer
end

Configuration

DuckDuckGo.configure do |config|
  config.secure = true           # Use HTTPS (default: true)
  config.user_agent = "MyApp/1.0"
  config.timeout = 30.seconds
  config.app_name = "my_app"     # Sent to DuckDuckGo for analytics
end

Testing with MockAdapter

mock_adapter = DuckDuckGo::HTTP::MockAdapter.new
mock_adapter.stub(/api\.duckduckgo\.com/, 200, %({"Heading": "Test", "Type": "A"}))

client = DuckDuckGo::Client.new(adapter: mock_adapter)
result = client.query("test")

API Limitations

The DuckDuckGo Instant Answer API provides:

• Topic summaries and definitions
• Disambiguation pages
• Instant answers (calculations, IP lookup, etc.)
• !Bang redirect URLs

It does not provide:

• Full web search results
• Image/video/news search

Contributing

1. Fork it (https://github.com/amscotti/duckduckgo/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT License - see LICENSE for details.

Contributors

• Anthony Scotti - creator and maintainer