searxng/docs/src/searx.results.rst

Engine Results

searx.results

The result items are organized in the :pycontainer.ResultContainer and rendered in the result template macros and result template files.

Contents

Result items

A result item is a python dictionary with dedicated keys and values. In the result list a standard result type is identified by the existence of the key url. Other result types are:

• :pysearx.results.suggestion
• :pysearx.results.answer
• :pysearx.results.correction
• :pysearx.results.infobox

The standard result type:

results.append({
    'template'      : str,

    # result_header

    'url'           : str,
    'title'         : str,
    'content'       : str,
    'img_src'       : str,
    'thumbnail'     : str,

    # result_sub_header

    'publishedDate' : datetime.datetime,
    'length'        : time.struct_time,
    'author'        : str,
    'metadata'      : str,
 })

template : str

Media type <result media types> of the result item. Name of the template file <result template files> from result_templates <searx/templates/simple/result_templates>. If unset, default.html is used.

Hint

Each standard result type of an engine can be of different media-types <result media types>.

Result template macros

result_header

Execpt image.html this macro is used in all result template files. Fields used in the template macro result_header <searx/templates/simple/macros.html>:

url : str

Link URL of the result item.

title : str

Link title of the result item.

img_src, thumbnail : str

URL of a image or thumbnail that is displayed in the result item.

result_sub_header

Execpt image.html this macro is used in all result template files. Fields used in the template macro result_sub_header <searx/templates/simple/macros.html>:

publishedDate : :pydatetime.datetime

The date on which the object was published.

length: :pytime.struct_time

Playing duration in seconds.

author : str

Author of the title.

metadata : str

Miscellaneous metadata.

engine_data_form

The engine_data_form macro is used in results,html <searx/templates/simple/results.html> in a HTML <form/> element. The intention of this macro is to pass data of a engine from one :pyresponse <searx.engines.demo_online.response> to the :pysearx.search.SearchQuery of the next :pyrequest <searx.engines.demo_online.request>.

Hint

The engine-data values are transfered to the next request when the user press the "next page" button. When a new search request is made, the enigine-data are removed from the client request.

To pass data, engine's response handler can append result items of typ engine_data. This is by example used to pass a token from the response to the next request:

def response(resp):
    ...
    results.append({
       'engine_data': token,
       'key': 'next_page_token',
    })
    ...
    return results

def request(query, params):
    page_token = params['engine_data'].get('next_page_token')

Result template files

The media types of the standard result type are the template files in the result_templates <searx/templates/simple/result_templates>.

default.html

Displays result fields from:

• macro result_header and
• macro result_sub_header

Additional fields used in the default.html <searx/templates/simple/result_templates/default.html>:

content : str

General text of the result item.

iframe_src : str

URL of an embedded <iframe> / the frame is collapsible.

audio_src : uri,

URL of an embedded <audio controls>.

code.html

Displays result fields from:

• macro result_header and
• macro result_sub_header

Additional fields used in the code.html <searx/templates/simple/result_templates/code.html>:

content : str

Description of the code fragment.

codelines : [line1, line2, ...]

Lines of the code fragment.

code_language : str

Name of the code language, the value is passed to :pypygments.lexers.get_lexer_by_name.

repository : str

URL of the repository of the code fragment.

images.html

Fields used in the images.html <searx/templates/simple/result_templates/images.html>:

title : str

Title of the image.

thumbnail_src : str

URL of a preview of the image.

img_src : str

URL of the full size image.

Image labels

content: str

Description of the image.

author: str

Name of the author of the image.

img_format : str

Format of the image.

source : str

Source of the image.

url : str

URL of the page from where the images comes from (source).

videos.html

Displays result fields from:

• macro result_header and
• macro result_sub_header

Additional fields used in the videos.html <searx/templates/simple/result_templates/videos.html>:

iframe_src : str

URL of an embedded <iframe> / the frame is collapsible.

content : str

Description of the code fragment.

map.html

Displays result fields from:

• macro result_header and
• macro result_sub_header

Additional fields used in the map.html <searx/templates/simple/result_templates/map.html>:

content : str

Description of the item.

address_label : str

Label of the address / default _('address').

geojson : GeoJSON

Geometries mapped to HTMLElement.dataset (data-map-geojson) and used by Leaflet.

boundingbox : [ min-lon, min-lat, max-lon, max-lat]

A bbox area defined by min longitude , min latitude , max longitude and max latitude. The bounding box is mapped to HTMLElement.dataset (data-map-boundingbox) and is used by Leaflet.

longitude, latitude : str

Geographical coordinates, mapped to HTMLElement.dataset (data-map-lon, data-map-lat) and is used by Leaflet.

address : {...}

A dicticonary with the address data:

address = {
    'name'          : str,  # name of object
    'road'          : str,  # street name of object
    'house_number'  : str,  # house number of object
    'postcode'      : str,  # postcode of object
    'country'       : str,  # country of object
    'country_code'  : str,
    'locality'      : str,
}

country_code : str

Country code of the object.

locality : str

The name of the city, town, township, village, borough, etc. in which this object is located.

links : [link1, link2, ...]

A list of links with labels:

links.append({
    'label'       : str,
    'url'         : str,
    'url_label'   : str,  # set by some engines but unused (oscar)
})

data : [data1, data2, ...]

A list of additional data, shown in two columns and containing a label and value.

data.append({
   'label'   : str,
   'value'   : str,
   'key'     : str,  # set by some engines but unused
})

type : str # set by some engines but unused (oscar)

Tag label from OSM_KEYS_TAGS['tags'] <update_osm_keys_tags.py>.

type_icon : str # set by some engines but unused (oscar)

Type's icon.

osm : {...}

OSM-type and OSM-ID, can be used to Lookup OSM data (Nominatim). There is also a discussion about "place_id is not a persistent id" and the perma_id.

osm = {
    'type': str,
    'id':   str,
}

type : str

Type of osm-object (if OSM-Result).

id :

ID of osm-object (if OSM-Result).

Hint

The osm property is set by engine openstreetmap.py, but it is not used in the map.html template yet.

products.html

Displays result fields from:

• macro result_header and
• macro result_sub_header

Additional fields used in the products.html <searx/templates/simple/result_templates/products.html>:

content : str

Description of the product.

price : str

The price must include the currency.

shipping : str

Shipping details.

source_country : str

Place from which the shipment is made.

torrent.html

Displays result fields from:

• macro result_header and
• macro result_sub_header

Additional fields used in the torrent.html <searx/templates/simple/result_templates/torrent.html>:

magnetlink:

URL of the magnet link.

torrentfile

URL of the torrent file.

seed : int

Number of seeders.

leech : int

Number of leecher

filesize : int

Size in Bytes (rendered to human readable unit of measurement).

files : int

Number of files.

Suggestion results

searx.results.suggestion

Answer results

searx.results.answer

Correction results

searx.results.correction

Infobox results

searx.results.infobox

Result container

searx.results.container

results.core

searx.results.core