/share/site/duckduckgo/api.tx

  1<style type="text/css">
  2pre {
  3  background-color:#EEE;
  4  font-family:Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,serif;
  5  padding:10px;
  6  word-wrap: break-word;
  7  font-size: 10pt;
  8  white-space: pre-wrap; /* css-3 */
  9  white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
 10  white-space: -pre-wrap; /* Opera 4-6 */
 11  white-space: -o-pre-wrap; /* Opera 7 */
 12  margin-top:5px;
 13}
 14</style>
 15
 16<div id="special_page_header"><: l('Instant Answer API') :></div>
 17
 18<: include "untranslated.tx" :>
 19
 20<div style="margin-bottom:30px;"></div>
 21Our Instant Answer API gives you free access to many of our instant answers like:
 22<a href="http://duckduckgo.com/?q=valley+forge+national+park">topic summaries</a> 
 23(<a href="http://api.duckduckgo.com/?q=valley+forge+national+park&format=json&pretty=1">API example</a>), 
 24<a href="http://duckduckgo.com/?q=simpsons+characters">categories</a>
 25(<a href="http://api.duckduckgo.com/?q=simpsons+characters&format=json&pretty=1">API example</a>), 
 26<a href="http://duckduckgo.com/?q=apple">disambiguation</a>  
 27(<a href="http://api.duckduckgo.com/?q=apple&format=json&pretty=1">API example</a>),
 28and
 29<a href="/bang.html">!bang redirects</a>
 30(<a href="http://api.duckduckgo.com/?q=!imdb+rushmore&format=json&pretty=1&no_redirect=1">API example</a>).
 31
 32<div style="margin-bottom:20px;"></div>
 33This 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.
 34
 35<div style="margin-bottom:20px;"></div>
 36Our 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.
 37
 38<p style="margin-top: 20px;">
 39Our 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.
 40
 41<p style="margin-top: 20px;">
 42  This API serves <a href="/traffic.html">over 10,000,000 queries a day</a> for a variety of uses, e.g.:
 43
 44<ul>
 45<li>Defining people, places, things, words and concepts, e.g. for side-bars, onMouseover or onHiglight.
 46<li>Providing direct links to other services (via <a href="/bang.html">!bang syntax</a>).
 47<li>Listing related topics.
 48<li>Giving official sites when available.
 49</ul>
 50
 51<p style="margin-top: 25px;">
 52To 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.
 53<br><a href="http://api.duckduckgo.com/?q=DuckDuckGo&format=json&pretty=1">http://api.duckduckgo.com/?q=DuckDuckGo&format=json</a>  
 54
 55<p style="margin-top: 25px;">
 56Here are the requirements for use: 
 57<ul>
 58<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). 
 59<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).
 60<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.
 61</ul>
 62
 63Our overall goal is to get more people using DuckDuckGo, so please keep that in mind as well. 
 64
 65<p style="margin-top: 25px;">
 66Here are the return fields:
 67<p style="margin-top: 5px;">
 68<pre>
 69Abstract: topic summary (can contain HTML, e.g. italics)
 70AbstractText: topic summary (with no HTML)
 71AbstractSource: name of Abstract source
 72AbstractURL: deep link to expanded topic page in AbstractSource
 73Image: link to image that goes with Abstract
 74Heading: name of topic that goes with Abstract
 75
 76Answer: instant answer
 77AnswerType: 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).
 78
 79Definition: dictionary definition (may differ from Abstract)
 80DefinitionSource: name of Definition source
 81DefinitionURL: deep link to expanded definition page in DefinitionSource
 82
 83RelatedTopics: array of internal links to related topics associated with Abstract
 84  Result: HTML link(s) to related topic(s)
 85  FirstURL: first URL in Result
 86  Icon: icon associated with related topic(s)
 87    URL: URL of icon
 88    Height: height of icon (px)
 89    Width: width of icon (px)
 90  Text: text from first URL
 91
 92Results: array of external links associated with Abstract
 93  Result: HTML link(s) to external site(s)
 94  FirstURL: first URL in Result
 95  Icon: icon associated with FirstURL
 96    URL: URL of icon
 97    Height: height of icon (px)
 98    Width: width of icon (px)
 99  Text: text from FirstURL
100
101Type: response category, i.e. A (article), D (disambiguation), C (category), N (name), E (exclusive), or nothing.
102
103Redirect: !bang redirect URL
104</pre>
105
106<p style="margin-top: 20px;">
107Here are all the parameters:
108<p style="margin-top: 5px;">
109<pre>
110q: query
111
112
113format: output format (json or xml)
114
115If format=='json', you can also pass:
116
117callback: function to callback (JSONP format)
118pretty: 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>)
119
120
121no_redirect: 1 to skip HTTP redirects (for !bang commands).
122
123
124no_html: 1 to remove HTML from text, e.g. bold and italics.
125
126
127skip_disambig: 1 to skip disambiguation (D) Type.
128</pre>
129
130<p style="margin-top: 35px;">
131<b>Notes</b>
132<ul>
133<li class="small">As this is an instant answer API, most deep queries (non topic names) will be blank.
134<pre>
135{
136Abstract: ""
137AbstractText: ""
138AbstractSource: ""
139AbstractURL: ""
140Image: ""
141Heading: ""
142Answer: ""
143Redirect: ""
144AnswerType: ""
145Definition: ""
146DefinitionSource: ""
147DefinitionURL: ""
148RelatedTopics: [ ]
149Results: [ ]
150Type: ""
151}
152</pre>
153<!--
154<p style="margin-top: 5px;">
155<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. 
156//-->
157
158<p style="margin-top: 5px;">
159<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).
160
161<p style="margin-top: 5px;">
162<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).
163
164<p style="margin-top: 5px;">
165<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.
166
167<p style="margin-top: 5px;">
168<li class="small">Queries can be case sensitive e.g. 
169<a href="/?q=blackberry">blackberry</a> (<a href="http://api.duckduckgo.com/?q=blackberry&format=json&pretty=1">API example</a>)
170vs
171<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).
172
173<p style="margin-top: 5px;">
174<li class="small">This API can work over an encrypted (SSL/HTTPS) connection.
175
176</ul>
177
178
179
180<p style="margin-top: 35px;">
181<b>FAQ</b>
182
183<p style="margin-top: 10px;">
184<i>Are there supporting library integrations?</i> 
185<p style="margin-top: 5px;">
186<ul>
187<span class="small">
188<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>.
189<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>. 
190<li><a href="http://pypi.python.org/pypi/duckduckgo2/0.2">Python library</a> by mikejs. 
191<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. 
192<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>
193<li><a href="https://github.com/andrewrjones/ruby-duck-duck-go">Ruby Gem</a> by <a href="http://andrew-jones.com/">Andrew Jones</a>
194<li><a href="https://github.com/ajanicij/goduckgo">Go library</a> by <a href="https://github.com/ajanicij">ajanicij</a>
195<li><a href="https://github.com/lukewendling/ddg-api">Node.js module</a> by <a href="http://lukewendling.com">Luke Wendling</a>
196<li><a href="https://github.com/jawerty/node-ddg">Node.js wrapper</a> by <a href="http://jawerty.github.io/">Jared Wright</a>
197<li><a href="https://github.com/timkly/DuckDuckGo.Net">.Net Library</a> by <a href="http://tk.id.au/">Tim Kelly</a>
198<li>If you make another supporting library, we'll add it here!
199</span>
200</ul>
201
202
203<p style="margin-top: 25px;">
204<i>Why is x query blank? Where are all the Web links like on the main site?</i> 
205
206<p style="margin-top: 5px;">
207<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>
208
209
210<p style="margin-top: 25px;">
211<i>Why is my query blank? I see an Instant Answer on the main site!</i> 
212
213<p style="margin-top: 5px;">
214<span class="small">
215Not 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.
216</span>
217
218
219<p style="margin-top: 25px;">
220<i>Can I use the DuckDuckGo name to help promote what I've developed with the API?</i>
221
222<p style="margin-top: 5px;">
223<span class="small">
224Yes 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. 
225</span>
226
227
228<p style="margin-top: 25px;">
229<i>Is this API open source?</i>
230
231<p style="margin-top: 5px;">
232<span class="small">
233No, 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>.
234</span>
235
236
237<p style="margin-top: 25px;">
238<i>Are there technical limits on API use?</i>
239
240<p style="margin-top: 5px;">
241<span class="small">
242We 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. 
243</span>
244
245
246<p style="margin-top: 25px;">
247If you have more questions, please <a href="http://help.duckduckgo.com/customer/portal/articles/775109">let us know</a>.