Skip to content
This repository

DuckDuckGo instant answer plugin infrastructure

README.md

DuckDuckHack Developer Overview

What is this?

DuckDuckGo is a general purpose search engine. We've created a platform called DuckDuckHack that enables developers to write open source plugins on top of the search engine (like add-ons for Firefox). DuckDuckGo plugins react to search queries and provide useful instant answers above traditional links.

DuckDuckHack is very much a work in progress. Some plugin types have better interfaces than others. We will be improving the platform based on your feedback.

This site will always have the latest platform information.

Why should I make plugins?

We hope you will consider making DuckDuckGo plugins to:

Overview

There are currently four types of DuckDuckGo plugins:

Goodies — calculations and cheat sheets.

Spice — external API calls.

Fathead — keyword databases.

Longtail — full-text data.

  • Examples: wikipedia, lyrics, stack overflow, etc.
  • Status: alpha
  • Languages: Perl, Node, Ruby, Python (maybe others)
  • Involves: formatting data sets to answer general queries.

Getting Started

Step 1.  Decide what you want to work on. If you don't have any ideas, start here.

Step 2.  Figure out your plugin type (see Plugin Types above). If the right type is not obvious, please ask us. Sometimes multiple plugin types could work, and we can help you figure out which one would work best.

Step 3.  Fork the right repository (GitHub instructions):

Step 4.  Now it's choose-your-own-adventure time!

Advanced Stuff

Testing Triggers

Pre-requisites:

Before reading this section, make sure you've at least worked through the basic tutorial.


Step 1.  Install our DuckDuckHack utility called duckpan:

curl http://duckpan.org/install.pl | perl

This script will setup local::lib, which is a way to install Perl modules without changing your base Perl installation. (If you already use local::lib or perlbrew, don't worry, this script will intelligently use what you already have.)

If you didn't have a local::lib before running the install script, you will need to run the script twice. It should tell you when like this:

please now re-login to your user account and run it again!

If everything works, you should see this at the end:

EVERYTHING OK! You can now go hacking! :)

Note that with local::lib now installed, you can easily install Perl modules with cpanm.

cpanm App::DuckPAN
App::DuckPAN is up to date.

Step 2.  Go to your fork of the repository (a directory or folder on your computer).

cd zeroclickinfo-goodies/

Step 3.  Install the repository requirements using duckpan.

duckpan installdeps

This command will install all the Perl modules used by the DuckDuckGo plugins within your local repository. These requirements are defined in the /dist.ini file (at the root).

Step 4. Add your plugin.

Make a new file in the lib/DDG/Goodie/ directory for Goodies or the lib/DDG/Spice/ directory for Spice. The name of the file is the name of the plugin followed by the extension .pm because it is a Perl package. For example, if the name of your plugin was TestPlugin, the file would be TestPlugin.pm.

Step 5. Test your trigger(s) interactively.

Type this command at the command line.

duckpan goodie test

First, this command will output all of the plugins available in your local plugin repository.

Using the following DDG::Goodie plugins:

 - DDG::Goodie::Xor (Words)
 - DDG::Goodie::SigFigs (Words)
 - DDG::Goodie::EmToPx (Words)
 - DDG::Goodie::Length (Words)
 - DDG::Goodie::ABC (Words)
 - DDG::Goodie::Chars (Words)
 ...

You should see your plugin in there as well. When the output is finished it gives you an interactive prompt.

(Empty query for ending test)
Query:

Now you can type in any query and see what the response will be.

Query: chars this is a test

DDG::ZeroClickInfo  {
    Parents       WWW::DuckDuckGo::ZeroClickInfo
    Linear @ISA   DDG::ZeroClickInfo, WWW::DuckDuckGo::ZeroClickInfo, Moo::Object
    public methods (3) : is_cached, new, ttl
    private methods (0)
    internals: {
        answer   14,
        answer_type   "chars",
        is_cached   1
    }
}

There is a lot of debugging output, but you will want to pay special attention to the internals section.

    internals: {
        answer   14,
        answer_type   "chars",
        is_cached   1
    }

Here you can see the answer returned, as well as any zci keywords (by default there will be a default answer_type and is_cached value).

Simply hit enter (a blank query) to exit interactive mode.

Query:

\_o< Thanks for testing!

Where to go now:

Something went wrong with that request. Please try again.