Searching¶

All searches go through SearchParams. It’s a Pydantic model, so invalid combinations are caught and raise ValidationError before any HTTP request is made.

Basic search¶

from xanax import Wallhaven, SearchParams

client = Wallhaven()
results = client.search(SearchParams(query="anime"))

Search query syntax¶

The query field supports Wallhaven’s tag-based search syntax:

# Require a tag
SearchParams(query="+nature")

# Exclude a tag
SearchParams(query="-water")

# Combine
SearchParams(query="+nature -water +forest")

# Search by tag ID
SearchParams(query="id:1")

# Search by uploader
SearchParams(query="@username")

# Free-text (untagged search)
SearchParams(query="mountain lake")

Categories¶

Control which content categories to include. By default all three are included.

from xanax import SearchParams
from xanax.enums import Category

# Only anime
params = SearchParams(categories=[Category.ANIME])

# General and people, no anime
params = SearchParams(categories=[Category.GENERAL, Category.PEOPLE])

# All categories (default)
params = SearchParams()  # categories defaults to all three

Purity¶

from xanax.enums import Purity

# SFW only (default)
SearchParams(purity=[Purity.SFW])

# SFW and sketchy
SearchParams(purity=[Purity.SFW, Purity.SKETCHY])

# NSFW (requires API key)
SearchParams(purity=[Purity.NSFW])

Note

Requesting NSFW without an API key raises AuthenticationError immediately, before the request is sent.

Sorting¶

from xanax.enums import Sort, Order

SearchParams(sorting=Sort.DATE_ADDED)   # newest first (default)
SearchParams(sorting=Sort.RELEVANCE)    # best match
SearchParams(sorting=Sort.RANDOM)       # random
SearchParams(sorting=Sort.VIEWS)        # most viewed
SearchParams(sorting=Sort.FAVORITES)    # most favorited
SearchParams(sorting=Sort.TOPLIST)      # toplist (requires top_range)

# Direction
SearchParams(sorting=Sort.DATE_ADDED, order=Order.ASC)  # oldest first

Toplist¶

When sorting by toplist, you must also provide a time range:

from xanax.enums import Sort, TopRange

SearchParams(sorting=Sort.TOPLIST, top_range=TopRange.ONE_MONTH)

Available ranges:

Value	Period
`TopRange.ONE_DAY`	Past 24 hours
`TopRange.THREE_DAYS`	Past 3 days
`TopRange.ONE_WEEK`	Past week
`TopRange.ONE_MONTH`	Past month
`TopRange.THREE_MONTHS`	Past 3 months
`TopRange.SIX_MONTHS`	Past 6 months
`TopRange.ONE_YEAR`	Past year

Setting top_range without sorting=Sort.TOPLIST raises ValidationError.

Resolutions¶

Filter to exact resolutions. Format: WIDTHxHEIGHT.

SearchParams(resolutions=["1920x1080", "2560x1440"])

Invalid formats raise ValidationError.

Aspect ratios¶

Filter by aspect ratio. Format: WIDTHxHEIGHT or WIDTH:HEIGHT.

SearchParams(ratios=["16x9", "4x3"])
SearchParams(ratios=["16:9"])

Colors¶

Filter wallpapers by dominant color. Use the Color enum:

from xanax.enums import Color

SearchParams(colors=[Color.BLUE, Color.TEAL])

All 29 color options are available as Color.* enum members.

File type¶

from xanax.enums import FileType

SearchParams(file_type=FileType.PNG)
SearchParams(file_type=FileType.JPG)

Similar wallpapers¶

Find wallpapers similar to a given ID:

SearchParams(like="94x38z")

Pagination¶

SearchParams(page=2)

Pages start at 1. Setting page=0 raises a pydantic.ValidationError.

Random seed¶

For random-sorted results, a seed locks the shuffle so you get consistent pages:

from xanax.enums import Sort

params = SearchParams(sorting=Sort.RANDOM, seed="abc123")

Seeds are 6 alphanumeric characters. An invalid seed raises ValidationError.

When using auto-pagination with iter_pages(), seeds returned by the API are carried forward automatically — you don’t need to manage them yourself.

Copying params with changes¶

SearchParams is immutable (Pydantic frozen model). Use with_page() and with_seed() to get new instances:

params = SearchParams(query="anime", sorting=Sort.TOPLIST, top_range=TopRange.ONE_MONTH)

page2 = params.with_page(2)
seeded = params.with_seed("xyz789")

Both return a new SearchParams with the single field updated and everything else preserved.

Full example¶

from xanax import Wallhaven, SearchParams
from xanax.enums import Category, Color, FileType, Order, Purity, Sort, TopRange

client = Wallhaven(api_key="your-api-key")

params = SearchParams(
    query="+nature -water",
    categories=[Category.GENERAL, Category.ANIME],
    purity=[Purity.SFW, Purity.SKETCHY],
    sorting=Sort.TOPLIST,
    order=Order.DESC,
    top_range=TopRange.ONE_MONTH,
    resolutions=["1920x1080", "2560x1440"],
    ratios=["16x9"],
    colors=[Color.GREEN],
    file_type=FileType.PNG,
    page=1,
)

result = client.search(params)
print(f"Found {result.meta.total} wallpapers across {result.meta.last_page} pages")