searxng/docs/dev/engines/engine_overview.rst

Engine Overview

Further reading ..

• configured engines
• settings engine

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 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

Common options in the engine module

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	online [ref] <online engines> by default, other possibles values are: offline [ref] <offline engines> online_dictionary [ref] <online dictionary> online_currency [ref] <online currency> online_url_search [ref] <online url search>

Engine settings.yml

For a more detailed description, see settings engine in the settings.yml.

Common options in the engine setup (settings.yml)

argument	type	information
name	string	name of search-engine
engine	string	name of searxng-engine (file name without .py)
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. proxies : {http: socks5://proxy:port, https: socks5://proxy:port})

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'

The naming of overrides is arbitrary / recommended overrides are:

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.

If the engine_type is :pyonline <searx.search.processors.online.OnlineProcessor.get_params>

argument	type	default-value, information
url	str	''
method	str	'GET'
headers	set	{}
data	set	{}
cookies	set	{}
verify	bool	True
headers.User-Agent	str	a random User-Agent
category	str	current category, like 'general'
safesearch	int	0, between 0 and 2 (normal, moderate, strict)
time_range	Optional[str]	None, can be day, week, month, year
pageno	int	current pagenumber
searxng_locale	str	SearXNG's locale selected by user. Specific language code like 'en', 'en-US', or 'all' if unspecified.

If the engine_type is :pyonline_dictionary <searx.search.processors.online_dictionary.OnlineDictionaryProcessor.get_params>, in addition to the online <engine request online> arguments:

argument	type	default-value, information
from_lang	str	specific language code like 'en_US'
to_lang	str	specific language code like 'en_US'
query	str	the text query without the languages

If the engine_type is :pyonline_currency <searx.search.processors.online_currency.OnlineCurrencyProcessor.get_params>, in addition to the online <engine request online> arguments:

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

If the engine_type is :pyonline_url_search <searx.search.processors.online_url_search.OnlineUrlSearchProcessor.get_params>, in addition to the online <engine request online> arguments:

argument	type	default-value, information
search_url	dict	URLs from the search query: { 'http': str, 'ftp': str, 'data:image': str }

Specify Request

The function :pydef request(query, params): <searx.engines.demo_online.request> 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 template default, the parameter template must be set to the desired type.

default

Parameter of the default media type:

result-parameter	information
url	string, url of the result
title	string, title of the result
content	string, general result-text
publishedDate	:pydatetime.datetime, time of publish

images

Parameter of the images media type

result-parameter	Python type	information
template	:pystr	is set to images.html
url	:pystr	url to the result site
title	:pystr	title of the result
content	:pystr	description of the image
publishedDate	:pydatetime <datetime.datetime>	time of publish
img_src	:pystr	url to the result image
thumbnail_src	:pystr	url to a small-preview image
resolution	:pystr	the resolution of the image (e.g. 1920 x 1080 pixel)
img_format	:pystr	the format of the image (e.g. png)
filesize	:pystr	size of bytes in :pyhuman readable <searx.humanize_bytes> notation (e.g. MB for 1024 * 1024 Bytes filesize).

videos

Parameter of the videos media type:

result-parameter	information
template	is set to videos.html
=========================	=====================================================
url	string, url of the result
title	string, title of the result
content	(not implemented yet)
publishedDate	:pydatetime.datetime, time of publish
thumbnail	string, url to a small-preview image

torrent

Parameter of the torrent media type:

result-parameter	information
template	is set to torrent.html
=========================	=====================================================
url	string, url of the result
title	string, title of the result
content	string, general result-text
publishedDate	:pydatetime.datetime, time of publish (not implemented yet)
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

Parameter of the map media type:

result-parameter	information
template	is set to map.html
=========================	=====================================================
url	string, url of the result
title	string, title of the result
content	string, general result-text
publishedDate	:pydatetime.datetime, time of publish
latitude	latitude of result (in decimal format)
longitude	longitude of result (in decimal format)
boundingbox	boundingbox of result (array of 4. values [lat-min, lat-max, lon-min, lon-max])
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

Parameter of the paper media type / see BibTeX field types and BibTeX format

result-parameter	Python type	information
template	:pystr	is set to paper.html
title	:pystr	title of the result
content	:pystr	abstract
comments	:pystr	free text display in italic below the content
tags	:pyList <list>[:pystr]	free tag list
publishedDate	:pydatetime <datetime.datetime>	last publication date
type	:pystr	short description of medium type, e.g. book, pdf or html ...
authors	:pyList <list>[:pystr]	list of authors of the work (authors with a "s")
editor	:pystr	list of editors of a book
publisher	:pystr	name of the publisher
journal	:pystr	name of the journal or magazine the article was published in
volume	:pystr	volume number
pages	:pystr	page range where the article is
number	:pystr	number of the report or the issue number for a journal article
doi	:pystr	DOI number (like 10.1038/d41586-018-07848-2)
issn	:pyList <list>[:pystr]	ISSN number like 1476-4687
isbn	:pyList <list>[:pystr]	ISBN number like 9780201896831
pdf_url	:pystr	URL to the full article, the PDF version
html_url	:pystr	URL to full article, HTML version

packages

Parameter of the packages media type

result-parameter	Python type	information
template	:pystr	is set to packages.html
title	:pystr	title of the result
content	:pystr	abstract
package_name	:pystr	the name of the package
version	:pystr	the current version of the package
maintainer	:pystr	the maintainer or author of the project
publishedDate	:pydatetime <datetime.datetime>	date of latest update or release
tags	:pyList <list>[:pystr]	free tag list
popularity	:pystr	the popularity of the package, e.g. rating or download count
license_name	:pystr	the name of the license
license_url	:pystr	the web location of a license copy
homepage	:pystr	the url of the project's homepage
source_code_url	:pystr	the location of the project's source code