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