Skip to content

SauceNAO

Classes

SauceNAO

Bases: BaseSearchEngine[SauceNAOResponse]

API client for the SauceNAO image search engine.

Used for performing reverse image searches using SauceNAO service.

Attributes:

Name Type Description
base_url str

The base URL for SauceNAO searches.
params dict[str, Any]

The query parameters for SauceNAO search.
Source code in PicImageSearch/engines/saucenao.py 
 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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class SauceNAO(BaseSearchEngine[SauceNAOResponse]):
    """API client for the SauceNAO image search engine.

    Used for performing reverse image searches using SauceNAO service.

    Attributes:
        base_url (str): The base URL for SauceNAO searches.
        params (dict[str, Any]): The query parameters for SauceNAO search.
    """

    def __init__(
        self,
        base_url: str = "https://saucenao.com",
        api_key: Optional[str] = None,
        numres: int = 5,
        hide: int = 0,
        minsim: int = 30,
        output_type: int = 2,
        testmode: int = 0,
        dbmask: Optional[int] = None,
        dbmaski: Optional[int] = None,
        db: int = 999,
        dbs: Optional[list[int]] = None,
        **request_kwargs: Any,
    ):
        """Initializes a SauceNAO API client with specified configurations.

        Args:
            base_url (str): The base URL for SauceNAO searches, defaults to 'https://saucenao.com'.
            api_key (Optional[str]): API key for SauceNAO API access, required for full API functionality.
            numres (int): Number of results to return (1-40), defaults to 5.
            hide (int): Content filtering level (0-3), defaults to 0.
                0: Show all results
                1: Hide expected explicit results
                2: Hide expected questionable results
                3: Hide all but expected safe results
            minsim (int): Minimum similarity percentage for results (0-100), defaults to 30.
            output_type (int): Output format of search results, defaults to 2.
                0: HTML
                1: XML
                2: JSON
            testmode (int): If 1, performs a dry-run search without using search quota.
            dbmask (Optional[int]): Bitmask for enabling specific databases.
            dbmaski (Optional[int]): Bitmask for disabling specific databases.
            db (int): Database index to search from (0-999), defaults to 999 (all databases).
            dbs (Optional[list[int]]): List of specific database indices to search from.
            **request_kwargs (Any): Additional arguments passed to the HTTP client.

        Note:
            - API documentation: https://saucenao.com/user.php?page=search-api
            - Database indices: https://saucenao.com/tools/examples/api/index_details.txt
            - Using API key is recommended to avoid rate limits and access more features.
            - When `dbs` is provided, it takes precedence over `db` parameter.
        """
        base_url = f"{base_url}/search.php"
        super().__init__(base_url, **request_kwargs)
        params: dict[str, Any] = {
            "testmode": testmode,
            "numres": numres,
            "output_type": output_type,
            "hide": hide,
            "db": db,
            "minsim": minsim,
        }
        if api_key is not None:
            params["api_key"] = api_key
        if dbmask is not None:
            params["dbmask"] = dbmask
        if dbmaski is not None:
            params["dbmaski"] = dbmaski
        self.params = QueryParams(params)
        if dbs is not None:
            self.params = self.params.remove("db")
            for i in dbs:
                self.params = self.params.add("dbs[]", i)

    async def search(
        self,
        url: Optional[str] = None,
        file: Union[str, bytes, Path, None] = None,
        **kwargs: Any,
    ) -> SauceNAOResponse:
        """Performs a reverse image search on SauceNAO.

        This method supports two ways of searching:
            1. Search by image URL
            2. Search by uploading a local image file

        Args:
            url (Optional[str]): URL of the image to search.
            file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
            **kwargs (Any): Additional arguments passed to the parent class.

        Returns:
            SauceNAOResponse: An object containing:
                - Search results with similarity scores
                - Source information and thumbnails
                - Additional metadata (status code, search quotas)

        Raises:
            ValueError: If neither `url` nor `file` is provided.

        Note:
            - Only one of `url` or `file` should be provided.
            - API limits vary based on account type and API key usage.
            - Free accounts are limited to:
                * 150 searches per day
                * 4 searches per 30 seconds
            - Results are sorted by similarity score in descending order.
        """
        self._validate_args(url, file)

        params = self.params
        files: Optional[dict[str, Any]] = None

        if url:
            params = params.add("url", url)
        elif file:
            files = {"file": read_file(file)}

        resp = await self._make_request(
            method="post",
            params=params,
            files=files,
        )

        resp_json = json_loads(resp.text)
        resp_json.update({"status_code": resp.status_code})

        return SauceNAOResponse(resp_json, resp.url)

Attributes

params = self.params.add('dbs[]', i) instance-attribute

Functions

__init__(base_url='https://saucenao.com', api_key=None, numres=5, hide=0, minsim=30, output_type=2, testmode=0, dbmask=None, dbmaski=None, db=999, dbs=None, **request_kwargs)

Initializes a SauceNAO API client with specified configurations.

Parameters:

Name Type Description Default
base_url str

The base URL for SauceNAO searches, defaults to 'https://saucenao.com'.

 'https://saucenao.com'
api_key Optional[str]

API key for SauceNAO API access, required for full API functionality.

 None
numres int

Number of results to return (1-40), defaults to 5.

 5
hide int

Content filtering level (0-3), defaults to 0. 0: Show all results 1: Hide expected explicit results 2: Hide expected questionable results 3: Hide all but expected safe results

 0
minsim int

Minimum similarity percentage for results (0-100), defaults to 30.

 30
output_type int

Output format of search results, defaults to 2. 0: HTML 1: XML 2: JSON

 2
testmode int

If 1, performs a dry-run search without using search quota.

 0
dbmask Optional[int]

Bitmask for enabling specific databases.

 None
dbmaski Optional[int]

Bitmask for disabling specific databases.

 None
db int

Database index to search from (0-999), defaults to 999 (all databases).

 999
dbs Optional[list[int]]

List of specific database indices to search from.

 None
**request_kwargs Any

Additional arguments passed to the HTTP client.

 {}
Note
  • API documentation: https://saucenao.com/user.php?page=search-api
  • Database indices: https://saucenao.com/tools/examples/api/index_details.txt
  • Using API key is recommended to avoid rate limits and access more features.
  • When dbs is provided, it takes precedence over db parameter.
Source code in PicImageSearch/engines/saucenao.py 
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
def __init__(
    self,
    base_url: str = "https://saucenao.com",
    api_key: Optional[str] = None,
    numres: int = 5,
    hide: int = 0,
    minsim: int = 30,
    output_type: int = 2,
    testmode: int = 0,
    dbmask: Optional[int] = None,
    dbmaski: Optional[int] = None,
    db: int = 999,
    dbs: Optional[list[int]] = None,
    **request_kwargs: Any,
):
    """Initializes a SauceNAO API client with specified configurations.

    Args:
        base_url (str): The base URL for SauceNAO searches, defaults to 'https://saucenao.com'.
        api_key (Optional[str]): API key for SauceNAO API access, required for full API functionality.
        numres (int): Number of results to return (1-40), defaults to 5.
        hide (int): Content filtering level (0-3), defaults to 0.
            0: Show all results
            1: Hide expected explicit results
            2: Hide expected questionable results
            3: Hide all but expected safe results
        minsim (int): Minimum similarity percentage for results (0-100), defaults to 30.
        output_type (int): Output format of search results, defaults to 2.
            0: HTML
            1: XML
            2: JSON
        testmode (int): If 1, performs a dry-run search without using search quota.
        dbmask (Optional[int]): Bitmask for enabling specific databases.
        dbmaski (Optional[int]): Bitmask for disabling specific databases.
        db (int): Database index to search from (0-999), defaults to 999 (all databases).
        dbs (Optional[list[int]]): List of specific database indices to search from.
        **request_kwargs (Any): Additional arguments passed to the HTTP client.

    Note:
        - API documentation: https://saucenao.com/user.php?page=search-api
        - Database indices: https://saucenao.com/tools/examples/api/index_details.txt
        - Using API key is recommended to avoid rate limits and access more features.
        - When `dbs` is provided, it takes precedence over `db` parameter.
    """
    base_url = f"{base_url}/search.php"
    super().__init__(base_url, **request_kwargs)
    params: dict[str, Any] = {
        "testmode": testmode,
        "numres": numres,
        "output_type": output_type,
        "hide": hide,
        "db": db,
        "minsim": minsim,
    }
    if api_key is not None:
        params["api_key"] = api_key
    if dbmask is not None:
        params["dbmask"] = dbmask
    if dbmaski is not None:
        params["dbmaski"] = dbmaski
    self.params = QueryParams(params)
    if dbs is not None:
        self.params = self.params.remove("db")
        for i in dbs:
            self.params = self.params.add("dbs[]", i)
search(url=None, file=None, **kwargs) async

Performs a reverse image search on SauceNAO.

This method supports two ways of searching
  1. Search by image URL
  2. Search by uploading a local image file

Parameters:

Name Type Description Default
url Optional[str]

URL of the image to search.

 None
file Union[str, bytes, Path, None]

Local image file, can be a path string, bytes data, or Path object.

 None
**kwargs Any

Additional arguments passed to the parent class.

 {}

Returns:

Name Type Description
SauceNAOResponse SauceNAOResponse

An object containing: - Search results with similarity scores - Source information and thumbnails - Additional metadata (status code, search quotas)

Raises:

Type Description
ValueError

If neither url nor file is provided.
Note
  • Only one of url or file should be provided.
  • API limits vary based on account type and API key usage.
  • Free accounts are limited to:
    • 150 searches per day
    • 4 searches per 30 seconds
  • Results are sorted by similarity score in descending order.
Source code in PicImageSearch/engines/saucenao.py 
 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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
async def search(
    self,
    url: Optional[str] = None,
    file: Union[str, bytes, Path, None] = None,
    **kwargs: Any,
) -> SauceNAOResponse:
    """Performs a reverse image search on SauceNAO.

    This method supports two ways of searching:
        1. Search by image URL
        2. Search by uploading a local image file

    Args:
        url (Optional[str]): URL of the image to search.
        file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
        **kwargs (Any): Additional arguments passed to the parent class.

    Returns:
        SauceNAOResponse: An object containing:
            - Search results with similarity scores
            - Source information and thumbnails
            - Additional metadata (status code, search quotas)

    Raises:
        ValueError: If neither `url` nor `file` is provided.

    Note:
        - Only one of `url` or `file` should be provided.
        - API limits vary based on account type and API key usage.
        - Free accounts are limited to:
            * 150 searches per day
            * 4 searches per 30 seconds
        - Results are sorted by similarity score in descending order.
    """
    self._validate_args(url, file)

    params = self.params
    files: Optional[dict[str, Any]] = None

    if url:
        params = params.add("url", url)
    elif file:
        files = {"file": read_file(file)}

    resp = await self._make_request(
        method="post",
        params=params,
        files=files,
    )

    resp_json = json_loads(resp.text)
    resp_json.update({"status_code": resp.status_code})

    return SauceNAOResponse(resp_json, resp.url)

Functions