free
/
searx


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Engine overview &mdash; searx 0.8.0 documentation</title>
    
    <link rel="stylesheet" href="../_static/style.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.8.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="searx 0.8.0 documentation" href="../index.html" />
    <link rel="next" title="Search API" href="search_api.html" />
    <link rel="prev" title="Installation" href="install/installation.html" />
   
  
  <link media="only screen and (max-device-width: 480px)" href="../_static/small_flask.css" type= "text/css" rel="stylesheet" />
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">

  </head>
  <body role="document">  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="engine-overview">
<h1><a class="toc-backref" href="#id2">Engine overview</a><a class="headerlink" href="#engine-overview" title="Permalink to this headline">¶</a></h1>
<p>searx is a <a class="reference external" href="https://en.wikipedia.org/wiki/Metasearch_engine">metasearch-engine</a>,
so it uses different search engines to provide better results.</p>
<p>Because there is no general search API which could be used for every
search engine, an adapter has to be built between searx and the
external search engines. Adapters are stored under the folder
<a class="reference external" href="https://github.com/asciimoo/searx/tree/master/searx/engines">searx/engines</a>.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#engine-overview" id="id2">Engine overview</a><ul>
<li><a class="reference internal" href="#general-engine-configuration" id="id3">general engine configuration</a><ul>
<li><a class="reference internal" href="#engine-file" id="id4">engine file</a></li>
<li><a class="reference internal" href="#settings-yml" id="id5">settings.yml</a></li>
<li><a class="reference internal" href="#overrides" id="id6">overrides</a></li>
<li><a class="reference internal" href="#example-code" id="id7">example code</a></li>
</ul>
</li>
<li><a class="reference internal" href="#making-a-request" id="id8">making a request</a><ul>
<li><a class="reference internal" href="#passed-arguments" id="id9">passed arguments</a></li>
<li><a class="reference internal" href="#parsed-arguments" id="id10">parsed arguments</a></li>
<li><a class="reference internal" href="#id1" id="id11">example code</a></li>
</ul>
</li>
<li><a class="reference internal" href="#returned-results" id="id12">returned results</a><ul>
<li><a class="reference internal" href="#default" id="id13">default</a></li>
<li><a class="reference internal" href="#images" id="id14">images</a></li>
<li><a class="reference internal" href="#videos" id="id15">videos</a></li>
<li><a class="reference internal" href="#torrent" id="id16">torrent</a></li>
<li><a class="reference internal" href="#map" id="id17">map</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="general-engine-configuration">
<h2><a class="toc-backref" href="#id3">general engine configuration</a><a class="headerlink" href="#general-engine-configuration" title="Permalink to this headline">¶</a></h2>
<p>It is required to tell searx the type of results the engine provides. The
arguments can be set in the engine file or in the settings file
(normally <code class="docutils literal"><span class="pre">settings.yml</span></code>). The arguments in the settings file override
the ones in the engine file.</p>
<p>It does not matter if an option is stored in the engine file or in the
settings. However, the standard way is the following:</p>
<div class="section" id="engine-file">
<h3><a class="toc-backref" href="#id4">engine file</a><a class="headerlink" href="#engine-file" title="Permalink to this headline">¶</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="15%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument</th>
<th class="head">type</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>categories</td>
<td>list</td>
<td>pages, in which the engine is working</td>
</tr>
<tr class="row-odd"><td>paging</td>
<td>boolean</td>
<td>support multible pages</td>
</tr>
<tr class="row-even"><td>language_support</td>
<td>boolean</td>
<td>support language choosing</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="settings-yml">
<h3><a class="toc-backref" href="#id5">settings.yml</a><a class="headerlink" href="#settings-yml" title="Permalink to this headline">¶</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="14%" />
<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument</th>
<th class="head">type</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>name</td>
<td>string</td>
<td>name of search-engine</td>
</tr>
<tr class="row-odd"><td>engine</td>
<td>string</td>
<td>name of searx-engine (filename without .py)</td>
</tr>
<tr class="row-even"><td>shortcut</td>
<td>string</td>
<td>shortcut of search-engine</td>
</tr>
<tr class="row-odd"><td>timeout</td>
<td>string</td>
<td>specific timeout for search-engine</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="overrides">
<h3><a class="toc-backref" href="#id6">overrides</a><a class="headerlink" href="#overrides" title="Permalink to this headline">¶</a></h3>
<p>A few of the options have default values in the engine, but are
often overwritten by the settings. If <code class="docutils literal"><span class="pre">None</span></code> is assigned to an option
in the engine file, it has to be redefined in the settings,
otherwise searx will not start with that engine.</p>
<p>The naming of overrides is arbitrary. But the recommended
overrides are the following:</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="10%" />
<col width="66%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument</th>
<th class="head">type</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>base_url</td>
<td>string</td>
<td>base-url, can be overwritten to use same engine on other URL</td>
</tr>
<tr class="row-odd"><td>number_of_results</td>
<td>int</td>
<td>maximum number of results per request</td>
</tr>
<tr class="row-even"><td>language</td>
<td>string</td>
<td>ISO code of language and country like en_US</td>
</tr>
<tr class="row-odd"><td>api_key</td>
<td>string</td>
<td>api-key if required by engine</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="example-code">
<h3><a class="toc-backref" href="#id7">example code</a><a class="headerlink" href="#example-code" title="Permalink to this headline">¶</a></h3>
<div class="code python highlight-python"><div class="highlight"><pre><span class="c1"># engine dependent config</span>
<span class="n">categories</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;general&#39;</span><span class="p">]</span>
<span class="n">paging</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">language_support</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="making-a-request">
<h2><a class="toc-backref" href="#id8">making a request</a><a class="headerlink" href="#making-a-request" title="Permalink to this headline">¶</a></h2>
<p>To perform a search an URL have to be specified. In addition to
specifying an URL, arguments can be passed to the query.</p>
<div class="section" id="passed-arguments">
<h3><a class="toc-backref" href="#id9">passed arguments</a><a class="headerlink" href="#passed-arguments" title="Permalink to this headline">¶</a></h3>
<p>These arguments can be used to construct the search query. Furthermore,
parameters with default value can be redefined for special purposes.</p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="11%" />
<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument</th>
<th class="head">type</th>
<th class="head">default-value, information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>url</td>
<td>string</td>
<td><code class="docutils literal"><span class="pre">''</span></code></td>
</tr>
<tr class="row-odd"><td>method</td>
<td>string</td>
<td><code class="docutils literal"><span class="pre">'GET'</span></code></td>
</tr>
<tr class="row-even"><td>headers</td>
<td>set</td>
<td><code class="docutils literal"><span class="pre">{}</span></code></td>
</tr>
<tr class="row-odd"><td>data</td>
<td>set</td>
<td><code class="docutils literal"><span class="pre">{}</span></code></td>
</tr>
<tr class="row-even"><td>cookies</td>
<td>set</td>
<td><code class="docutils literal"><span class="pre">{}</span></code></td>
</tr>
<tr class="row-odd"><td>verify</td>
<td>boolean</td>
<td><code class="docutils literal"><span class="pre">True</span></code></td>
</tr>
<tr class="row-even"><td>headers.User-Agent</td>
<td>string</td>
<td>a random User-Agent</td>
</tr>
<tr class="row-odd"><td>category</td>
<td>string</td>
<td>current category, like <code class="docutils literal"><span class="pre">'general'</span></code></td>
</tr>
<tr class="row-even"><td>started</td>
<td>datetime</td>
<td>current date-time</td>
</tr>
<tr class="row-odd"><td>pageno</td>
<td>int</td>
<td>current pagenumber</td>
</tr>
<tr class="row-even"><td>language</td>
<td>string</td>
<td>specific language code like <code class="docutils literal"><span class="pre">'en_US'</span></code>, or <code class="docutils literal"><span class="pre">'all'</span></code> if unspecified</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="parsed-arguments">
<h3><a class="toc-backref" href="#id10">parsed arguments</a><a class="headerlink" href="#parsed-arguments" title="Permalink to this headline">¶</a></h3>
<p>The function <code class="docutils literal"><span class="pre">def</span> <span class="pre">request(query,</span> <span class="pre">params):</span></code> always returns the
<code class="docutils literal"><span class="pre">params</span></code> variable. Inside searx, the following paramters can be
used to specify a search request:</p>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="14%" />
<col width="71%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument</th>
<th class="head">type</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>url</td>
<td>string</td>
<td>requested url</td>
</tr>
<tr class="row-odd"><td>method</td>
<td>string</td>
<td>HTTP request method</td>
</tr>
<tr class="row-even"><td>headers</td>
<td>set</td>
<td>HTTP header information</td>
</tr>
<tr class="row-odd"><td>data</td>
<td>set</td>
<td>HTTP data information (parsed if <code class="docutils literal"><span class="pre">method</span> <span class="pre">!=</span> <span class="pre">'GET'</span></code>)</td>
</tr>
<tr class="row-even"><td>cookies</td>
<td>set</td>
<td>HTTP cookies</td>
</tr>
<tr class="row-odd"><td>verify</td>
<td>boolean</td>
<td>Performing SSL-Validity check</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="id1">
<h3><a class="toc-backref" href="#id11">example code</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<div class="code python highlight-python"><div class="highlight"><pre><span class="c1"># search-url</span>
<span class="n">base_url</span> <span class="o">=</span> <span class="s1">&#39;https://example.com/&#39;</span>
<span class="n">search_string</span> <span class="o">=</span> <span class="s1">&#39;search?{query}&amp;page={page}&#39;</span>

<span class="c1"># do search-request</span>
<span class="k">def</span> <span class="nf">request</span><span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="n">params</span><span class="p">):</span>
    <span class="n">search_path</span> <span class="o">=</span> <span class="n">search_string</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
        <span class="n">query</span><span class="o">=</span><span class="n">urlencode</span><span class="p">({</span><span class="s1">&#39;q&#39;</span><span class="p">:</span> <span class="n">query</span><span class="p">}),</span>
        <span class="n">page</span><span class="o">=</span><span class="n">params</span><span class="p">[</span><span class="s1">&#39;pageno&#39;</span><span class="p">])</span>

    <span class="n">params</span><span class="p">[</span><span class="s1">&#39;url&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">base_url</span> <span class="o">+</span> <span class="n">search_path</span>

    <span class="k">return</span> <span class="n">params</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="returned-results">
<h2><a class="toc-backref" href="#id12">returned results</a><a class="headerlink" href="#returned-results" title="Permalink to this headline">¶</a></h2>
<p>Searx is able to return results of different media-types.
Currently the following media-types are supported:</p>
<ul class="simple">
<li>default</li>
<li>images</li>
<li>videos</li>
<li>torrent</li>
<li>map</li>
</ul>
<p>To set another media-type as default, the parameter
<code class="docutils literal"><span class="pre">template</span></code> must be set to the desired type.</p>
<div class="section" id="default">
<h3><a class="toc-backref" href="#id13">default</a><a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="87%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">result-parameter</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>url</td>
<td>string, which is representing the url of the result</td>
</tr>
<tr class="row-odd"><td>title</td>
<td>string, which is representing the title of the result</td>
</tr>
<tr class="row-even"><td>content</td>
<td>string, which is giving a general result-text</td>
</tr>
<tr class="row-odd"><td>publishedDate</td>
<td><a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">datetime.datetime</a>, represent when the result is published</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="images">
<h3><a class="toc-backref" href="#id14">images</a><a class="headerlink" href="#images" title="Permalink to this headline">¶</a></h3>
<p>to use this template, the parameter</p>
<table border="1" class="docutils">
<colgroup>
<col width="11%" />
<col width="89%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">result-parameter</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>template</td>
<td>is set to <code class="docutils literal"><span class="pre">images.html</span></code></td>
</tr>
<tr class="row-odd"><td>url</td>
<td>string, which is representing the url to the result site</td>
</tr>
<tr class="row-even"><td>title</td>
<td>string, which is representing the title of the result <em>(partly implemented)</em></td>
</tr>
<tr class="row-odd"><td>content</td>
<td><em>(partly implemented)</em></td>
</tr>
<tr class="row-even"><td>publishedDate</td>
<td><a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">datetime.datetime</a>, represent when the result is published <em>(partly implemented)</em></td>
</tr>
<tr class="row-odd"><td>img_src</td>
<td>string, which is representing the url to the result image</td>
</tr>
<tr class="row-even"><td>thumbnail_src</td>
<td>string, which is representing the url to a small-preview image</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="videos">
<h3><a class="toc-backref" href="#id15">videos</a><a class="headerlink" href="#videos" title="Permalink to this headline">¶</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="87%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">result-parameter</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>template</td>
<td>is set to <code class="docutils literal"><span class="pre">videos.html</span></code></td>
</tr>
<tr class="row-odd"><td>url</td>
<td>string, which is representing the url of the result</td>
</tr>
<tr class="row-even"><td>title</td>
<td>string, which is representing the title of the result</td>
</tr>
<tr class="row-odd"><td>content</td>
<td><em>(not implemented yet)</em></td>
</tr>
<tr class="row-even"><td>publishedDate</td>
<td><a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">datetime.datetime</a>, represent when the result is published</td>
</tr>
<tr class="row-odd"><td>thumbnail</td>
<td>string, which is representing the url to a small-preview image</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="torrent">
<h3><a class="toc-backref" href="#id16">torrent</a><a class="headerlink" href="#torrent" title="Permalink to this headline">¶</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="90%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>result-parameter</td>
<td>information</td>
</tr>
<tr class="row-even"><td>template</td>
<td>is set to <code class="docutils literal"><span class="pre">`torrent.html`</span></code></td>
</tr>
<tr class="row-odd"><td>url</td>
<td>string, which is representing the url of the result</td>
</tr>
<tr class="row-even"><td>title</td>
<td>string, which is representing the title of the result</td>
</tr>
<tr class="row-odd"><td>content</td>
<td>string, which is giving a general result-text</td>
</tr>
<tr class="row-even"><td>publishedDate</td>
<td><a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">datetime.datetime</a>, represent when the result is published <em>(not implemented yet)</em></td>
</tr>
<tr class="row-odd"><td>seed</td>
<td>int, number of seeder</td>
</tr>
<tr class="row-even"><td>leech</td>
<td>int, number of leecher</td>
</tr>
<tr class="row-odd"><td>filesize</td>
<td>int, size of file in bytes</td>
</tr>
<tr class="row-even"><td>files</td>
<td>int, number of files</td>
</tr>
<tr class="row-odd"><td>magnetlink</td>
<td>string, which is the <a class="reference external" href="https://en.wikipedia.org/wiki/Magnet_URI_scheme">magnetlink</a> of the result</td>
</tr>
<tr class="row-even"><td>torrentfile</td>
<td>string, which is the torrentfile of the result</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="map">
<h3><a class="toc-backref" href="#id17">map</a><a class="headerlink" href="#map" title="Permalink to this headline">¶</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="16%" />
<col width="84%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">result-parameter</th>
<th class="head">information</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>url</td>
<td>string, which is representing the url of the result</td>
</tr>
<tr class="row-odd"><td>title</td>
<td>string, which is representing the title of the result</td>
</tr>
<tr class="row-even"><td>content</td>
<td>string, which is giving a general result-text</td>
</tr>
<tr class="row-odd"><td>publishedDate</td>
<td><a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">datetime.datetime</a>, represent when the result is published</td>
</tr>
<tr class="row-even"><td>latitude</td>
<td>latitude of result (in decimal format)</td>
</tr>
<tr class="row-odd"><td>longitude</td>
<td>longitude of result (in decimal format)</td>
</tr>
<tr class="row-even"><td>boundingbox</td>
<td>boundingbox of result (array of 4. values <code class="docutils literal"><span class="pre">[lat-min,</span> <span class="pre">lat-max,</span> <span class="pre">lon-min,</span> <span class="pre">lon-max]</span></code>)</td>
</tr>
<tr class="row-odd"><td>geojson</td>
<td>geojson of result (<a class="reference external" href="http://geojson.org">http://geojson.org</a>)</td>
</tr>
<tr class="row-even"><td>osm.type</td>
<td>type of osm-object (if OSM-Result)</td>
</tr>
<tr class="row-odd"><td>osm.id</td>
<td>id of osm-object (if OSM-Result)</td>
</tr>
<tr class="row-even"><td>address.name</td>
<td>name of object</td>
</tr>
<tr class="row-odd"><td>address.road</td>
<td>street adress of object</td>
</tr>
<tr class="row-even"><td>address.house_number</td>
<td>house number of object</td>
</tr>
<tr class="row-odd"><td>address.locality</td>
<td>city, place of object</td>
</tr>
<tr class="row-even"><td>address.postcode</td>
<td>postcode of object</td>
</tr>
<tr class="row-odd"><td>address.country</td>
<td>country of object</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper"><div class="sidebar_container body">
<h1>Searx</h1>
<ul>
    <li><a href="../index.html">Home</a></li>
    <li><a href="https://github.com/asciimoo/searx">Source</a></li>
    <li><a href="https://github.com/asciimoo/searx/wiki">Wiki</a></li>
    <li><a href="https://github.com/asciimoo/searx/wiki/Searx-instances">Public instances</a></li>
</ul>
<hr />
<ul>
    <li><a href="https://twitter.com/Searx_engine">Twitter</a></li>
    <li><a href="https://flattr.com/submit/auto?user_id=asciimoo&url=https://github.com/asciimoo/searx&title=searx&language=&tags=github&category=software">Flattr</a></li>
    <li><a href="https://gratipay.com/searx">Gratipay</a></li>
</ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; Copyright 2015, Adam Tauber.
    </div>
  </body>
</html>