saucenao-api 2.0.1

Wrapper for SauceNAO JSON API

saucenao_api

“The rough edges are a part of its charm”

Unofficial wrapper for the SauceNAO JSON API

Installation

This package requires Python 3.6 or later

pip install saucenao_api

Usage

from saucenao_api import SauceNao

sauce = SauceNao()
results = sauce.from_url('https://i.imgur.com/oZjCxGo.jpg')  # or from_file()

best = results[0]  # results sorted by similarity

The library attempts to provide a developer friendly container format for all results. Meaning, no matter if SauceNao returns a Pixiv source result or a more obscure source, you'll be able to easily pull the title, url, author and other useful information:

from saucenao_api import SauceNao
results = SauceNao().from_url('https://i.imgur.com/oZjCxGo.jpg')

len(results)   # 6
bool(results)  # True

# Request limits
results.short_remaining  # 4  (per 30 seconds limit)
results.long_remaining   # 99 (per day limit)

results[0].thumbnail     # temporary URL for picture preview
results[0].similarity    # 93.3
results[0].title         # めぐみん
results[0].url           # https://www.pixiv.net/member_illust.php?mode=medium&illust_id=77630170
results[0].author        # frgs

Video search results and book search results provide additional attributes:

from saucenao_api import SauceNao, VideoSauce, BookSauce
result = SauceNao().from_url('https://i.imgur.com/k9xlw6f.jpg')[0]

if isinstance(result, VideoSauce):
    result.part      # 02
    result.year      # 2009-2009
    result.est_time  # 00:05:32 / 00:21:10

elif isinstance(result, BookSauce):
    result.part

You can use the dir function to see all the attributes.

Advanced usage

from saucenao_api import SauceNao
from saucenao_api.params import DB, Hide, BgColor

sauce = SauceNao(api_key=None,          # Optional[str] 
                 testmode=0,            # int
                 dbmask=None,           # Optional[int]
                 dbmaski=None,          # Optional[int]
                 db=DB.ALL,             # int
                 numres=6,              # int
                 frame=1,               # int
                 hide=Hide.NONE,        # int
                 bgcolor=BgColor.NONE,  # int
)

The parameters frame, hide and bgcolor are taken from the main page and from the testing page, so their performance is not guaranteed. For the rest see SauceNAO User Config page (registration required).

Exceptions

All exceptions inherit from SauceNaoApiError for easy catching and handling. See errors.py file for details.

License

This package is based on pysaucenao.