Engine Overview¶
SearXNG is a metasearch-engine, so it uses different search engines to provide better results.
Because there is no general search API which could be used for every search engine, an adapter has to be built between SearXNG and the external search engines. Adapters are stored under the folder git://searx/engines.
General Engine Configuration¶
It is required to tell SearXNG the type of results the engine provides. The
arguments can be set in the engine file or in the settings file (normally
settings.yml
). The arguments in the settings file override the ones in the
engine file.
It does not matter if an option is stored in the engine file or in the settings. However, the standard way is the following:
Engine File¶
argument |
type |
information |
---|---|---|
categories |
list |
categories, in which the engine is working |
paging |
boolean |
support multiple pages |
time_range_support |
boolean |
support search time range |
engine_type |
str |
Engine settings.yml
¶
For a more detailed description, see engine: in the settings.yml.
argument |
type |
information |
---|---|---|
name |
string |
name of search-engine |
engine |
string |
name of searxng-engine (file name without |
enable_http |
bool |
enable HTTP (by default only HTTPS is enabled). |
shortcut |
string |
shortcut of search-engine |
timeout |
string |
specific timeout for search-engine |
display_error_messages |
boolean |
display error messages on the web UI |
proxies |
dict |
set proxies for a specific engine
(e.g. |
Overrides¶
A few of the options have default values in the namespace of the engine’s python
module, but are often overwritten by the settings. If None
is assigned to an
option in the engine file, it has to be redefined in the settings, otherwise
SearXNG will not start with that engine (global names with a leading underline can
be None
).
Here is an very simple example of the global names in the namespace of engine’s module:
# engine dependent config
categories = ['general']
paging = True
_non_overwritten_global = 'foo'
argument |
type |
information |
---|---|---|
base_url |
string |
base-url, can be overwritten to use same engine on other URL |
number_of_results |
int |
maximum number of results per request |
language |
string |
ISO code of language and country like en_US |
api_key |
string |
api-key if required by engine |
Making a Request¶
To perform a search an URL have to be specified. In addition to specifying an URL, arguments can be passed to the query.
Passed Arguments (request)¶
These arguments can be used to construct the search query. Furthermore, parameters with default value can be redefined for special purposes.
argument |
type |
default-value, information |
---|---|---|
url |
str |
|
method |
str |
|
headers |
set |
|
data |
set |
|
cookies |
set |
|
verify |
bool |
|
headers.User-Agent |
str |
a random User-Agent |
category |
str |
current category, like |
safesearch |
int |
|
time_range |
Optional[str] |
|
pageno |
int |
current pagenumber |
searxng_locale |
str |
SearXNG’s locale selected by user. Specific language code like
|
argument |
type |
default-value, information |
---|---|---|
from_lang |
str |
specific language code like |
to_lang |
str |
specific language code like |
query |
str |
the text query without the languages |
argument |
type |
default-value, information |
---|---|---|
amount |
float |
the amount to convert |
from |
str |
ISO 4217 code |
to |
str |
ISO 4217 code |
from_name |
str |
currency name |
to_name |
str |
currency name |
argument |
type |
default-value, information |
---|---|---|
search_url |
dict |
URLs from the search query: {
'http': str,
'ftp': str,
'data:image': str
}
|
Specify Request¶
The function def request(query, params):
always returns the params
variable, the
following parameters can be used to specify a search request:
argument |
type |
information |
---|---|---|
url |
str |
requested url |
method |
str |
HTTP request method |
headers |
set |
HTTP header information |
data |
set |
HTTP data information |
cookies |
set |
HTTP cookies |
verify |
bool |
Performing SSL-Validity check |
allow_redirects |
bool |
Follow redirects |
max_redirects |
int |
maximum redirects, hard limit |
soft_max_redirects |
int |
maximum redirects, soft limit. Record an error but don’t stop the engine |
raise_for_httperror |
bool |
True by default: raise an exception if the HTTP code of response is >= 300 |
Result Types (template
)¶
Each result item of an engine can be of different media-types. Currently the
following media-types are supported. To set another media-type as
default, the parameter template
must be set to the desired
type.
default
¶
result-parameter |
information |
---|---|
url |
string, url of the result |
title |
string, title of the result |
content |
string, general result-text |
publishedDate |
|
images
¶
result-parameter |
Python type |
information |
---|---|---|
template |
is set to |
|
url |
url to the result site |
|
title |
title of the result |
|
content |
description of the image |
|
publishedDate |
time of publish |
|
img_src |
url to the result image |
|
thumbnail_src |
url to a small-preview image |
|
resolution |
the resolution of the image (e.g. |
|
img_format |
the format of the image (e.g. |
|
filesize |
size of bytes in |
videos
¶
result-parameter |
information |
---|---|
template |
is set to |
url |
string, url of the result |
title |
string, title of the result |
content |
(not implemented yet) |
publishedDate |
|
thumbnail |
string, url to a small-preview image |
length |
|
views |
string, view count in humanized number format |
torrent
¶
result-parameter |
information |
---|---|
template |
is set to |
url |
string, url of the result |
title |
string, title of the result |
content |
string, general result-text |
publishedDate |
|
seed |
int, number of seeder |
leech |
int, number of leecher |
filesize |
int, size of file in bytes |
files |
int, number of files |
magnetlink |
string, magnetlink of the result |
torrentfile |
string, torrentfile of the result |
map
¶
result-parameter |
information |
---|---|
template |
is set to |
url |
string, url of the result |
title |
string, title of the result |
content |
string, general result-text |
publishedDate |
|
latitude |
latitude of result (in decimal format) |
longitude |
longitude of result (in decimal format) |
boundingbox |
boundingbox of result (array of 4. values
|
geojson |
geojson of result (https://geojson.org/) |
osm.type |
type of osm-object (if OSM-Result) |
osm.id |
id of osm-object (if OSM-Result) |
address.name |
name of object |
address.road |
street name of object |
address.house_number |
house number of object |
address.locality |
city, place of object |
address.postcode |
postcode of object |
address.country |
country of object |
paper
¶
result-parameter |
Python type |
information |
---|---|---|
template |
is set to |
|
title |
title of the result |
|
content |
abstract |
|
comments |
free text display in italic below the content |
|
tags |
free tag list |
|
publishedDate |
last publication date |
|
type |
short description of medium type, e.g. book, pdf or html … |
|
authors |
list of authors of the work (authors with a “s”) |
|
editor |
list of editors of a book |
|
publisher |
name of the publisher |
|
journal |
name of the journal or magazine the article was published in |
|
volume |
volume number |
|
pages |
page range where the article is |
|
number |
number of the report or the issue number for a journal article |
|
doi |
DOI number (like |
|
issn |
ISSN number like |
|
isbn |
ISBN number like |
|
pdf_url |
URL to the full article, the PDF version |
|
html_url |
URL to full article, HTML version |
packages
¶
result-parameter |
Python type |
information |
---|---|---|
template |
is set to |
|
title |
title of the result |
|
content |
abstract |
|
package_name |
the name of the package |
|
version |
the current version of the package |
|
maintainer |
the maintainer or author of the project |
|
publishedDate |
date of latest update or release |
|
tags |
free tag list |
|
popularity |
the popularity of the package, e.g. rating or download count |
|
license_name |
the name of the license |
|
license_url |
the web location of a license copy |
|
homepage |
the url of the project’s homepage |
|
source_code_url |
the location of the project’s source code |
|
links |
additional links in the form of |