# 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

Table 2 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] by default, other possibles values are: `offline` [ref] `online_dictionary` [ref] `online_currency` [ref] `online_url_search` [ref]

### Engine `settings.yml`

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

Table 3 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'

Table 4 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.

Table 5 If the `engine_type` is `online`
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.

Table 6 If the `engine_type` is `online_dictionary`, in addition to the 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

Table 7 If the `engine_type` is `online_currency`, in addition to the 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

Table 8 If the `engine_type` is `online_url_search`, in addition to the 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 `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`

Table 9 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 | `datetime.datetime`, time of publish

### `images`

Table 10 Parameter of the images media type
result-parameter | Python type | information
--- | --- | ---
template | `str` | is set to `images.html`
url | `str` | url to the result site
title | `str` | title of the result
content | `str` | description of the image
publishedDate | `datetime` | time of publish
img_src | `str` | url to the result image
thumbnail_src | `str` | url to a small-preview image
resolution | `str` | the resolution of the image (e.g. `1920 x 1080` pixel)
img_format | `str` | the format of the image (e.g. `png`)
filesize | `str` | size of bytes in `human readable` notation (e.g. `MB` for 1024 * 1024 Bytes filesize).

### `videos`

Table 11 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 | `datetime.datetime`, time of publish
thumbnail | string, url to a small-preview image
length | `datetime.timedelta`, duration of result
views | string, view count in humanized number format

### `torrent`

Table 12 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 | `datetime.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`

Table 13 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 | `datetime.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`

Table 14 Parameter of the paper media type / see BibTeX field types and BibTeX format
result-parameter | Python type | information
--- | --- | ---
template | `str` | is set to `paper.html`
title | `str` | title of the result
content | `str` | abstract
comments | `str` | free text display in italic below the content
tags | `List`[`str`] | free tag list
publishedDate | `datetime` | last publication date
type | `str` | short description of medium type, e.g. book, pdf or html …
authors | `List`[`str`] | list of authors of the work (authors with a “s”)
editor | `str` | list of editors of a book
publisher | `str` | name of the publisher
journal | `str` | name of the journal or magazine the article was published in
volume | `str` | volume number
pages | `str` | page range where the article is
number | `str` | number of the report or the issue number for a journal article
doi | `str` | DOI number (like `10.1038/d41586-018-07848-2`)
issn | `List`[`str`] | ISSN number like `1476-4687`
isbn | `List`[`str`] | ISBN number like `9780201896831`
pdf_url | `str` | URL to the full article, the PDF version
html_url | `str` | URL to full article, HTML version

### `packages`

Table 15 Parameter of the packages media type
result-parameter | Python type | information
--- | --- | ---
template | `str` | is set to `packages.html`
title | `str` | title of the result
content | `str` | abstract
package_name | `str` | the name of the package
version | `str` | the current version of the package
maintainer | `str` | the maintainer or author of the project
publishedDate | `datetime` | date of latest update or release
tags | `List`[`str`] | free tag list
popularity | `str` | the popularity of the package, e.g. rating or download count
license_name | `str` | the name of the license
license_url | `str` | the web location of a license copy
homepage | `str` | the url of the project’s homepage
source_code_url | `str` | the location of the project’s source code
links | `dict` | additional links in the form of `{'link_name': 'http://example.com'}`