@@ -0,0 +1,314 @@
5+searx is a `metasearch-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__,
6+so it is using different search engines to provide better results.
8+Because there is no general search-api which can be used for every
9+search-engine, there must be build an adapter between searx and the
10+external search-engine. This adapters are stored in the folder
11+`*searx/engines* <https://github.com/asciimoo/searx/tree/master/searx/engines>`__,
12+and this site is build to make an general documentation about this
19+general engine configuration
20+----------------------------
22+It is required to tell searx what results can the engine provide. The
23+arguments can be inserted in the engine file, or in the settings file
24+(normally ``settings.yml``). The arguments in the settings file override
25+the one in the engine file.
27+Really, it is for most options no difference if there are contained in
28+the engine-file or in the settings. But there is a standard where to
29+place specific arguments by default.
35++---------------------+-----------+-----------------------------------------+
36+| argument | type | information |
37++=====================+===========+=========================================+
38+| categories | list | pages, in which the engine is working |
39++---------------------+-----------+-----------------------------------------+
40+| paging | boolean | support multible pages |
41++---------------------+-----------+-----------------------------------------+
42+| language\_support | boolean | support language choosing |
43++---------------------+-----------+-----------------------------------------+
48++------------+----------+-----------------------------------------------+
49+| argument | type | information |
50++============+==========+===============================================+
51+| name | string | name of search-engine |
52++------------+----------+-----------------------------------------------+
53+| engine | string | name of searx-engine (filename without .py) |
54++------------+----------+-----------------------------------------------+
55+| shortcut | string | shortcut of search-engine |
56++------------+----------+-----------------------------------------------+
57+| timeout | string | specific timeout for search-engine |
58++------------+----------+-----------------------------------------------+
63+There are some options, with have default values in the engine, but are
64+often overwritten by the settings. If the option is assigned in the
65+engine-file with ``None`` it has to be redefined in the settings,
66+otherwise searx is not starting with that engine.
68+The naming of that overrides can be wathever you want. But we recommend
69+the using of already used overrides if possible:
71++-----------------------+----------+--------------------------------------------------------------+
72+| argument | type | information |
73++=======================+==========+==============================================================+
74+| base\_url | string | base-url, can be overwrite to use same engine on other url |
75++-----------------------+----------+--------------------------------------------------------------+
76+| number\_of\_results | int | maximum number of results per request |
77++-----------------------+----------+--------------------------------------------------------------+
78+| language | string | ISO code of language and country like en\_US |
79++-----------------------+----------+--------------------------------------------------------------+
80+| api\_key | string | api-key if required by engine |
81++-----------------------+----------+--------------------------------------------------------------+
88+ # engine dependent config
89+ categories = ['general']
91+ language_support = True
96+To perform a search you have to specific at least a url on which the
102+This arguments can be used to calculate the search-query. Furthermore,
103+some of that parameters are filled with default values which can be
104+changed for special purpose.
106++----------------------+------------+------------------------------------------------------------------------+
107+| argument | type | default-value, informations |
108++======================+============+========================================================================+
109+| url | string | ``''`` |
110++----------------------+------------+------------------------------------------------------------------------+
111+| method | string | ``'GET'`` |
112++----------------------+------------+------------------------------------------------------------------------+
113+| headers | set | ``{}`` |
114++----------------------+------------+------------------------------------------------------------------------+
115+| data | set | ``{}`` |
116++----------------------+------------+------------------------------------------------------------------------+
117+| cookies | set | ``{}`` |
118++----------------------+------------+------------------------------------------------------------------------+
119+| verify | boolean | ``True`` |
120++----------------------+------------+------------------------------------------------------------------------+
121+| headers.User-Agent | string | a random User-Agent |
122++----------------------+------------+------------------------------------------------------------------------+
123+| category | string | current category, like ``'general'`` |
124++----------------------+------------+------------------------------------------------------------------------+
125+| started | datetime | current date-time |
126++----------------------+------------+------------------------------------------------------------------------+
127+| pageno | int | current pagenumber |
128++----------------------+------------+------------------------------------------------------------------------+
129+| language | string | specific language code like ``'en_US'``, or ``'all'`` if unspecified |
130++----------------------+------------+------------------------------------------------------------------------+
135+The function ``def request(query, params):`` is always returning the
136+``params`` variable back. Inside searx, the following paramters can be
137+used to specific a search-request:
139++------------+-----------+----------------------------------------------------------+
140+| argument | type | information |
141++============+===========+==========================================================+
142+| url | string | requested url |
143++------------+-----------+----------------------------------------------------------+
144+| method | string | HTTP request methode |
145++------------+-----------+----------------------------------------------------------+
146+| headers | set | HTTP header informations |
147++------------+-----------+----------------------------------------------------------+
148+| data | set | HTTP data informations (parsed if ``method != 'GET'``) |
149++------------+-----------+----------------------------------------------------------+
150+| cookies | set | HTTP cookies |
151++------------+-----------+----------------------------------------------------------+
152+| verify | boolean | Performing SSL-Validity check |
153++------------+-----------+----------------------------------------------------------+
161+ base_url = 'https://example.com/'
162+ search_string = 'search?{query}&page={page}'
165+ def request(query, params):
166+ search_path = search_string.format(
167+ query=urlencode({'q': query}),
168+ page=params['pageno'])
170+ params['url'] = base_url + search_path
177+Searx has the possiblity to return results in different media-types.
178+Currently the following media-types are supported:
186+to set another media-type as default, you must set the parameter
187+``template`` to the required type.
192++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
193+| result-parameter | information |
194++====================+====================================================================================================================================+
195+| url | string, which is representing the url of the result |
196++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
197+| title | string, which is representing the title of the result |
198++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
199+| content | string, which is giving a general result-text |
200++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
201+| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published |
202++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
207+to use this template, the parameter
209++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
210+| result-parameter | information |
211++====================+===========================================================================================================================================================+
212+| template | is set to ``images.html`` |
213++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
214+| url | string, which is representing the url to the result site |
215++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
216+| title | string, which is representing the title of the result *(partly implemented)* |
217++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
218+| content | *(partly implemented)* |
219++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
220+| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published *(partly implemented)* |
221++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
222+| img\_src | string, which is representing the url to the result image |
223++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
224+| thumbnail\_src | string, which is representing the url to a small-preview image |
225++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
230++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
231+| result-parameter | information |
232++====================+====================================================================================================================================+
233+| template | is set to ``videos.html`` |
234++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
235+| url | string, which is representing the url of the result |
236++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
237+| title | string, which is representing the title of the result |
238++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
239+| content | *(not implemented yet)* |
240++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
241+| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published |
242++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
243+| thumbnail | string, which is representing the url to a small-preview image |
244++--------------------+------------------------------------------------------------------------------------------------------------------------------------+
249++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
250+| result-parameter | information |
251++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
252+| template | is set to ```torrent.html``` |
253++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
254+| url | string, which is representing the url of the result |
255++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
256+| title | string, which is representing the title of the result |
257++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
258+| content | string, which is giving a general result-text |
259++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
260+| publishedDate | [datetime.datetime](https://docs.python.org/2/library/datetime.html#datetime-objects), represent when the result is published _(not implemented yet)_ |
261++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
262+| seed | int, number of seeder |
263++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
264+| leech | int, number of leecher |
265++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
266+| filesize | int, size of file in bytes |
267++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
268+| files | int, number of files |
269++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
270+| magnetlink | string, which is the [magnetlink](https://en.wikipedia.org/wiki/Magnet_URI_scheme) of the result |
271++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
272+| torrentfile | string, which is the torrentfile of the result |
273++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
279++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
280+| result-parameter | information |
281++=========================+====================================================================================================================================+
282+| url | string, which is representing the url of the result |
283++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
284+| title | string, which is representing the title of the result |
285++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
286+| content | string, which is giving a general result-text |
287++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
288+| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published |
289++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
290+| latitude | latitude of result (in decimal format) |
291++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
292+| longitude | longitude of result (in decimal format) |
293++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
294+| boundingbox | boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``) |
295++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
296+| geojson | geojson of result (http://geojson.org) |
297++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
298+| osm.type | type of osm-object (if OSM-Result) |
299++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
300+| osm.id | id of osm-object (if OSM-Result) |
301++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
302+| address.name | name of object |
303++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
304+| address.road | street adress of object |
305++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
306+| address.house\_number | house number of object |
307++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
308+| address.locality | city, place of object |
309++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
310+| address.postcode | postcode of object |
311++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
312+| address.country | country of object |
313++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+