.oO SearXNG Developer Documentation Oo.
Loading...
Searching...
No Matches
marginalia.py
Go to the documentation of this file.
1# SPDX-License-Identifier: AGPL-3.0-or-later
2"""`Marginalia Search`_ is an independent open source Internet search engine
3operating out of Sweden. It is principally developed and operated by Viktor
4Lofgren .
5
6.. _Marginalia Search:
7 https://about.marginalia-search.com/
8
9Configuration
10=============
11
12The engine has the following required settings:
13
14- :py:obj:`api_key`
15
16You can configure a Marginalia engine by:
17
18.. code:: yaml
19
20 - name: marginalia
21 engine: marginalia
22 shortcut: mar
23 api_key: ...
24
25Implementations
26===============
27
28"""
29from __future__ import annotations
30
31import typing as t
32from urllib.parse import urlencode, quote_plus
33from searx.utils import searxng_useragent
34from searx.result_types import EngineResults
35from searx.extended_types import SXNG_Response
36
37about = {
38 "website": "https://marginalia.nu",
39 "wikidata_id": None,
40 "official_api_documentation": "https://about.marginalia-search.com/article/api/",
41 "use_official_api": True,
42 "require_api_key": True,
43 "results": "JSON",
44}
45
46base_url = "https://api.marginalia.nu"
47safesearch = True
48categories = ["general"]
49paging = False
50results_per_page = 20
51api_key = None
52"""To get an API key, please follow the instructions from `Key and license`_
53
54.. _Key and license:
55 https://about.marginalia-search.com/article/api/
56
57"""
58
59
60class ApiSearchResult(t.TypedDict):
61 """Marginalia's ApiSearchResult_ class definition.
62
63 .. _ApiSearchResult:
64 https://github.com/MarginaliaSearch/MarginaliaSearch/blob/master/code/services-application/api-service/java/nu/marginalia/api/model/ApiSearchResult.java
65 """
66
67 url: str
68 title: str
69 description: str
70 quality: float
71 format: str
72 details: str
73
74
75class ApiSearchResults(t.TypedDict):
76 """Marginalia's ApiSearchResults_ class definition.
77
78 .. _ApiSearchResults:
79 https://github.com/MarginaliaSearch/MarginaliaSearch/blob/master/code/services-application/api-service/java/nu/marginalia/api/model/ApiSearchResults.java
80 """
81
82 license: str
83 query: str
84 results: list[ApiSearchResult]
85
86
87def request(query: str, params: dict[str, t.Any]):
88
89 query_params = {
90 "count": results_per_page,
91 "nsfw": min(params["safesearch"], 1),
92 }
93
94 params["url"] = f"{base_url}/{api_key}/search/{quote_plus(query)}?{urlencode(query_params)}"
95 params["headers"]["User-Agent"] = searxng_useragent()
96
97
98def response(resp: SXNG_Response):
99
100 res = EngineResults()
101 resp_json: ApiSearchResults = resp.json() # type: ignore
102
103 for item in resp_json.get("results", []):
104 res.add(
105 res.types.MainResult(
106 title=item["title"],
107 url=item["url"],
108 content=item.get("description", ""),
109 )
110 )
111
112 return res
113
114
115def init(engine_settings: dict[str, t.Any]):
116
117 _api_key = engine_settings.get("api_key")
118 if not _api_key:
119 logger.error("missing api_key: see https://about.marginalia-search.com/article/api")
120 return False
121
122 if _api_key == "public":
123 logger.error("invalid api_key (%s): see https://about.marginalia-search.com/article/api", api_key)
124
125 return True
init(dict[str, t.Any] engine_settings)
request(str query, dict[str, t.Any] params)
Definition marginalia.py:87
response(SXNG_Response resp)
Definition marginalia.py:98