/share/site/duckduckgo/api.tx

<style type="text/css">
pre {
  background-color:#EEE;
  font-family:Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,serif;
  padding:10px;
  word-wrap: break-word;
  font-size: 10pt;
  white-space: pre-wrap; /* css-3 */
  white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
  white-space: -pre-wrap; /* Opera 4-6 */
  white-space: -o-pre-wrap; /* Opera 7 */
  margin-top:5px;
}
</style>

<div id="special_page_header"><: l('Instant Answer API') :></div>

<: include "untranslated.tx" :>

<div style="margin-bottom:30px;"></div>
Our Instant Answer API gives you free access to many of our instant answers like:
<a href="http://duckduckgo.com/?q=valley+forge+national+park">topic summaries</a> 
(<a href="http://api.duckduckgo.com/?q=valley+forge+national+park&format=json&pretty=1">API example</a>), 
<a href="http://duckduckgo.com/?q=simpsons+characters">categories</a>
(<a href="http://api.duckduckgo.com/?q=simpsons+characters&format=json&pretty=1">API example</a>), 
<a href="http://duckduckgo.com/?q=apple">disambiguation</a>  
(<a href="http://api.duckduckgo.com/?q=apple&format=json&pretty=1">API example</a>),
and
<a href="/bang.html">!bang redirects</a>
(<a href="http://api.duckduckgo.com/?q=!imdb+rushmore&format=json&pretty=1&no_redirect=1">API example</a>).

<div style="margin-bottom:20px;"></div>
This API does not include all of our links, however. That is, it is not a full search results API or a way to get DuckDuckGo results into your applications beyond our instant answers. Because of the way <a href="http://help.duckduckgo.com/customer/portal/articles/216399">we generate our search results</a>, we unfortunately do not have the rights to fully syndicate our results. For the same reason, we cannot allow framing our results without our branding. Please see <a href="http://help.duckduckgo.com/customer/portal/articles/775109">our partnerships page</a> for more info on guidelines and getting in touch with us.

<div style="margin-bottom:20px;"></div>
Our long-term goal is for <a href="https://duckduckgo.com/goodies/">all of our instant answers</a> to be available through this open API. Many of these instant answers are open source via our <a href="http://duckduckhack.com/">DuckDuckHack</a> platform. Using that platform, you can add your own APIs and data sources as well.

<p style="margin-top: 20px;">
Our instant answers come from a variety of sources, including <a href="http://wikipedia.org">Wikipedia</a>, <a href="http://wikia.com/">Wikia</a>, <a href="http://crunchbase.com">Crunchbase</a>, <a href="http://github.com">GitHub</a>, <a href="http://wikihow.com">WikiHow</a>, <a href="http://thefreedictionary.com">The Free Dictionary</a> &ndash; over 100 in total.

<p style="margin-top: 20px;">
  This API serves <a href="/traffic.html">over 10,000,000 queries a day</a> for a variety of uses, e.g.:

<ul>
<li>Defining people, places, things, words and concepts, e.g. for side-bars, onMouseover or onHiglight.
<li>Providing direct links to other services (via <a href="/bang.html">!bang syntax</a>).
<li>Listing related topics.
<li>Giving official sites when available.
</ul>

<p style="margin-top: 25px;">
To consume it yourself, you can use one of the language libraries listed below or simply add '&format=json' (or xml if you have a death wish) onto any query URL in the api subdomain, e.g.
<br><a href="http://api.duckduckgo.com/?q=DuckDuckGo&format=json&pretty=1">http://api.duckduckgo.com/?q=DuckDuckGo&format=json</a>  

<p style="margin-top: 25px;">
Here are the requirements for use: 
<ul>
<li>Attribution in each place you use our API for both us and any underlying source. For the source, you can link to the source's relevant detail page. For us, you can say <a href="https://duckduckgo.com/">Results from DuckDuckGo</a> with our logo (and link to the specific result page). 
<li>Non-commercial use unless you get <a href="http://help.duckduckgo.com/customer/portal/articles/775109">email approval from us</a> (though we're generally fine with anything that isn't sketchy).
<li>Use a descriptive <a href="http://help.duckduckgo.com/customer/portal/articles/448610">t parameter</a>, i.e. append &t=nameofapp to your requests.
</ul>

Our overall goal is to get more people using DuckDuckGo, so please keep that in mind as well. 

<p style="margin-top: 25px;">
Here are the return fields:
<p style="margin-top: 5px;">
<pre>
Abstract: topic summary (can contain HTML, e.g. italics)
AbstractText: topic summary (with no HTML)
AbstractSource: name of Abstract source
AbstractURL: deep link to expanded topic page in AbstractSource
Image: link to image that goes with Abstract
Heading: name of topic that goes with Abstract

Answer: instant answer
AnswerType: type of Answer, e.g. calc, color, digest, info, ip, iploc, phone, pw, rand, regexp, unicode, upc, or zip (see <a href="http://duckduckgo.com/goodies.html">goodies</a> & <a href="http://duckduckgo.com/tech.html">tech</a> pages for examples).

Definition: dictionary definition (may differ from Abstract)
DefinitionSource: name of Definition source
DefinitionURL: deep link to expanded definition page in DefinitionSource

RelatedTopics: array of internal links to related topics associated with Abstract
  Result: HTML link(s) to related topic(s)
  FirstURL: first URL in Result
  Icon: icon associated with related topic(s)
    URL: URL of icon
    Height: height of icon (px)
    Width: width of icon (px)
  Text: text from first URL

Results: array of external links associated with Abstract
  Result: HTML link(s) to external site(s)
  FirstURL: first URL in Result
  Icon: icon associated with FirstURL
    URL: URL of icon
    Height: height of icon (px)
    Width: width of icon (px)
  Text: text from FirstURL

Type: response category, i.e. A (article), D (disambiguation), C (category), N (name), E (exclusive), or nothing.

Redirect: !bang redirect URL
</pre>

<p style="margin-top: 20px;">
Here are all the parameters:
<p style="margin-top: 5px;">
<pre>
q: query


format: output format (json or xml)

If format=='json', you can also pass:

callback: function to callback (JSONP format)
pretty: 1 to make JSON look pretty (like JSONView for <a href="https://chrome.google.com/extensions/detail/chklaanhfefbnpoihckbnefhakgolnmc">Chrome</a>/<a href="https://addons.mozilla.org/en-US/firefox/addon/10869/">Firefox</a>)


no_redirect: 1 to skip HTTP redirects (for !bang commands).


no_html: 1 to remove HTML from text, e.g. bold and italics.


skip_disambig: 1 to skip disambiguation (D) Type.
</pre>

<p style="margin-top: 35px;">
<b>Notes</b>
<ul>
<li class="small">As this is an instant answer API, most deep queries (non topic names) will be blank.
<pre>
{
Abstract: ""
AbstractText: ""
AbstractSource: ""
AbstractURL: ""
Image: ""
Heading: ""
Answer: ""
Redirect: ""
AnswerType: ""
Definition: ""
DefinitionSource: ""
DefinitionURL: ""
RelatedTopics: [ ]
Results: [ ]
Type: ""
}
</pre>
<!--
<p style="margin-top: 5px;">
<li class="small">If there is no icon for a given Topic or Result, Icon will be a blank hash, i.e. {}, instead of a hash with every sub-field being an empty string. 
//-->

<p style="margin-top: 5px;">
<li class="small">Icons, i.e. the underlying images, may be greater than their specified Width/Height. You should explicitly set them to the specified measurements (if provided).

<p style="margin-top: 5px;">
<li class="small">For disambiguation pages (Type=='D'), RelatedTopics can be grouped into sections. In that case, RelatedTopics is an array of hashes. Each hash has a Name key and a Topics array matching the above RelatedTopics description. If you want to avoid this case altogether, use the disambiguation skip parameter (skip_disambig).

<p style="margin-top: 5px;">
<li class="small">For <a href="/bang.html">!bang commands</a>, the redirect will happen at the HTTP level (since that is fastest), but it will also be returned in the content (for parsing). If you don't want the redirect to happen in the HTTP header, use the no_redirect flag.

<p style="margin-top: 5px;">
<li class="small">Queries can be case sensitive e.g. 
<a href="/?q=blackberry">blackberry</a> (<a href="http://api.duckduckgo.com/?q=blackberry&format=json&pretty=1">API example</a>)
vs
<a href="/?q=BlackBerry">BlackBerry</a> (<a href="http://api.duckduckgo.com/?q=BlackBerry&format=json&pretty=1">API example</a>). In the first case (lowercase blackberry) it returns a disambiguation page; in the latter case (MixedCase BlackBerry) it returns info primarily about the device (inferring what you meant from the case).

<p style="margin-top: 5px;">
<li class="small">This API can work over an encrypted (SSL/HTTPS) connection.

</ul>



<p style="margin-top: 35px;">
<b>FAQ</b>

<p style="margin-top: 10px;">
<i>Are there supporting library integrations?</i> 
<p style="margin-top: 5px;">
<ul>
<span class="small">
<li>You can consume this API via <a href="http://www.mashape.com/apis/DuckDuckGo%20Zero-click%20Info">Mashape</a>, which provides PHP, Ruby, Python, Objective-C and Java (including Android) libraries. To do so, <a href="http://www.mashape.com/account/request-alpha-invite?apiName=DuckDuckGo%20Zero-click%20Info">sign up</a> (use the code DUCKDUCK) and <a href="http://www.mashape.com/account/login?apiName=DuckDuckGo%20Zero-click%20Info">login</a>.
<li><a href="http://search.cpan.org/perldoc?WWW::DuckDuckGo">Perl module</a> & <a href="http://search.cpan.org/perldoc?duckduckgo">command line app</a> by <a href="http://twitter.com/#!/raudssus">@raudssus</a>. 
<li><a href="http://pypi.python.org/pypi/duckduckgo2/0.2">Python library</a> by mikejs. 
<li><a href="http://dhruvbird.com/ddb/zc.html">Zero-click jQuery Search Widget</a> by <a href="http://twitter.com/#!/dhruvbird">@dhruvbird</a> that provides info for you in iframe format. 
<li><a href="https://github.com/SiegfriedEhret/jddg">jddg jQuery plugin</a> [<a href="http://dev.federalbureauofinhumanity.org/jddg/demo/">demo</a>] by <a href="http://federalbureauofinhumanity.org/">Siegfried Ehret</a>
<li><a href="https://github.com/andrewrjones/ruby-duck-duck-go">Ruby Gem</a> by <a href="http://andrew-jones.com/">Andrew Jones</a>
<li><a href="https://github.com/ajanicij/goduckgo">Go library</a> by <a href="https://github.com/ajanicij">ajanicij</a>
<li><a href="https://github.com/lukewendling/ddg-api">Node.js module</a> by <a href="http://lukewendling.com">Luke Wendling</a>
<li><a href="https://github.com/jawerty/node-ddg">Node.js wrapper</a> by <a href="http://jawerty.github.io/">Jared Wright</a>
<li><a href="https://github.com/timkly/DuckDuckGo.Net">.Net Library</a> by <a href="http://tk.id.au/">Tim Kelly</a>
<li>If you make another supporting library, we'll add it here!
</span>
</ul>


<p style="margin-top: 25px;">
<i>Why is x query blank? Where are all the Web links like on the main site?</i> 

<p style="margin-top: 5px;">
<span class="small">This is an Instant Answer API, and not a full results API. However, there are some Web links within it, e.g. official sites. Please see the second paragraph at the top for more info.</span>


<p style="margin-top: 25px;">
<i>Why is my query blank? I see an Instant Answer on the main site!</i> 

<p style="margin-top: 5px;">
<span class="small">
Not all of our instant answers are available right now via this API for a variety of reasons, though it is our long term goal to make them so. However, if you would like to see something in particular please <a href="/feedback.html">let us know</a>, and perhaps we can prioritize making it happen.
</span>


<p style="margin-top: 25px;">
<i>Can I use the DuckDuckGo name to help promote what I've developed with the API?</i>

<p style="margin-top: 5px;">
<span class="small">
Yes and no. We do not want to confuse users into thinking that your application was made by us. Please see <a href="http://help.duckduckgo.com/customer/portal/articles/775109">our partnerships page</a> for more info on guidelines and getting in touch with us. 
</span>


<p style="margin-top: 25px;">
<i>Is this API open source?</i>

<p style="margin-top: 5px;">
<span class="small">
No, though many of the instant answers it provides are open source via our <a href="http://duckduckhack.com/">DuckDuckHack platform</a>, which is completely open source. For more information on DuckDuckGo open source, please see <a href="http://help.dukgo.com/customer/portal/articles/216390-open-source">this help article</a>.
</span>


<p style="margin-top: 25px;">
<i>Are there technical limits on API use?</i>

<p style="margin-top: 5px;">
<span class="small">
We simply do not have the resources to support high queries per second (QPS) for a single machine. Generally, this isn't a problem because our API is designed to be used client-side by individual users after they take some specific action (like a search or right-click). We also get a lot of botnet attacks. As a result, there is automatic throttling for API requests that will probably not effect you if you use the API in a distributed fashion (i.e. on your application's front-end). For specific situations we also provide higher limits. If you feel you may be in such a situation, please <a href="http://help.dukgo.com/customer/portal/articles/775109-partnerships">reach out</a>. For legal limits, please see above for attribution and other requirements. 
</span>


<p style="margin-top: 25px;">
If you have more questions, please <a href="http://help.duckduckgo.com/customer/portal/articles/775109">let us know</a>.