Skip to main content

​
Overview

The WallWidgy API allows you to combine multiple filters to narrow down your wallpaper results. You can filter by category, color, device type, and control the number of results returned.

​
Available query parameters

All filters are optional and can be combined:
  • category - Filter by wallpaper category (anime, art, nature, etc.)
  • color - Filter by primary or secondary color
  • type - Filter by device type (desktop or mobile)
  • count - Number of random wallpapers to return (1-10, default: 1)

​
Basic filtering

​
Single filter examples

curl "https://wallwidgy.com/api/wallpapers?category=anime"

​
Combining multiple filters

​
Category + device type

Get mobile wallpapers from a specific category: 
curl "https://wallwidgy.com/api/wallpapers?category=nature&type=mobile"

​
Category + color

Find wallpapers in a specific category with a certain color: 
curl "https://wallwidgy.com/api/wallpapers?category=art&color=blue"

​
Color + device type

Get desktop wallpapers with a specific color: 
curl "https://wallwidgy.com/api/wallpapers?color=black&type=desktop"

​
Triple and quad filtering

​
Category + color + device type

curl "https://wallwidgy.com/api/wallpapers?category=anime&color=blue&type=mobile"

​
All filters combined

curl "https://wallwidgy.com/api/wallpapers?category=nature&color=green&type=desktop&count=5"

​
Response structure

When you combine filters, the API returns: 
{
  "wallpapers": [
    "https://wallwidgy.com/wallpapers/wallpapers_abc123.webp",
    "https://wallwidgy.com/wallpapers/wallpapers_xyz789.webp"
  ],
  "count": 2,
  "category": "nature",
  "type": "desktop",
  "color": "green"
}
The API returns the actual filter values applied in the response, making it easy to verify which filters were used.

​
Filter behavior

​
Filter precedence

Filters are applied in this order:
  1. Category filter (if specified)
  2. Color filter (if specified)
  3. Device type filter (if specified)
  4. Random selection based on count

​
Empty results

If no wallpapers match your filter combination, you’ll receive a 404 error: 
{
  "error": "No wallpapers found with color 'purple'"
}
Start with broader filters and add more specific ones. For example, first try category=anime, then add &color=blue, then &type=mobile.

​
Fallback behavior

If a device type filter returns no results, the API falls back to showing all types within the other filters (category and color).

​
Best practices

  1. Start broad, then narrow - Begin with one or two filters, then add more
  2. Check response count - The API tells you how many wallpapers matched
  3. Use valid values - See the categories and colors guides for valid values
  4. URL encode parameters - Always encode special characters in URLs

​
URL encoding examples

When using filters with special characters, make sure to URL encode them: 
curl "https://wallwidgy.com/api/wallpapers?category=anime&color=blue"
Most HTTP libraries (like fetch in JavaScript or requests in Python) handle URL encoding automatically when you pass parameters as an object.

Build docs developers (and LLMs) love

Get started for freeTalk to us