/share/site/duckduckgo/api.tx
Unknown | 247 lines | 190 code | 57 blank | 0 comment | 0 complexity | 5341197ab1f770eb5b395d482dcd2558 MD5 | raw file
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> – 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>.