Skip to main content

Overview

The WallWidgy API analyzes wallpapers and extracts both primary and secondary colors. You can filter wallpapers using the color query parameter to find images that match your preferred color scheme.

How color filtering works

Each wallpaper in the collection has:
  • Primary colors - The dominant colors in the image
  • Secondary colors - Supporting colors that appear in the image
The API searches both primary and secondary colors when you apply a color filter.

Common colors

These colors are frequently available in the collection:

Black

Dark, bold wallpapers

White

Clean, bright wallpapers

Gray

Neutral, balanced wallpapers

Red

Bold, energetic wallpapers

Blue

Calm, cool wallpapers

Green

Natural, fresh wallpapers

Yellow

Bright, cheerful wallpapers

Orange

Warm, vibrant wallpapers

Purple

Rich, creative wallpapers

Pink

Soft, playful wallpapers

Brown

Earthy, warm wallpapers

Cyan

Cool, digital wallpapers

Additional color values

The API also supports these color variations:
  • silver - Metallic gray tones
  • gold - Warm metallic tones
  • teal - Blue-green tones
  • navy - Dark blue tones
  • maroon - Dark red tones
  • olive - Yellow-green tones
  • lime - Bright yellow-green
  • aqua - Light blue tones
  • magenta - Bright pink-purple
  • beige - Light brown tones
  • ivory - Off-white tones
  • khaki - Light brown-yellow

Basic usage

Filter by color

curl "https://wallwidgy.com/api/wallpapers?color=blue"

Color examples

Black wallpapers

Perfect for dark themes and AMOLED screens:
curl "https://wallwidgy.com/api/wallpapers?color=black&count=5"

Blue wallpapers

Calm and cool tones:
curl "https://wallwidgy.com/api/wallpapers?color=blue&count=3"

White wallpapers

Clean and minimal:
curl "https://wallwidgy.com/api/wallpapers?color=white"

Red wallpapers

Bold and energetic:
curl "https://wallwidgy.com/api/wallpapers?color=red&count=5"

Combining with other filters

Color + category

Get blue nature wallpapers:
curl "https://wallwidgy.com/api/wallpapers?color=blue&category=nature"

Color + device type

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

Color + category + device type

Get desktop anime wallpapers with blue tones:
curl "https://wallwidgy.com/api/wallpapers?color=blue&category=anime&type=desktop"

Response format

The response includes the color filter in the metadata:
{
  "wallpapers": [
    "https://wallwidgy.com/wallpapers/wallpapers_blue_001.webp"
  ],
  "count": 1,
  "category": "all",
  "type": "all",
  "color": "blue"
}

Error handling

If no wallpapers match the color:
{
  "error": "No wallpapers found with color 'violet'"
}
Color names are case-insensitive. Both blue and Blue work the same way.

Practical examples

Theme-based color picker

const themeColors = {
  dark: 'black',
  light: 'white',
  ocean: 'blue',
  forest: 'green',
  sunset: 'orange',
  night: 'purple'
};

async function fetchThemeWallpaper(theme, count = 3) {
  const color = themeColors[theme];
  
  if (!color) {
    throw new Error(`Unknown theme: ${theme}`);
  }
  
  const response = await fetch(
    `https://wallwidgy.com/api/wallpapers?color=${color}&count=${count}`
  );
  
  return await response.json();
}

// Usage
const oceanWallpapers = await fetchThemeWallpaper('ocean', 5);
console.log(oceanWallpapers);

Color palette generator

async function getColorPalette(colors, countPerColor = 2) {
  const promises = colors.map(color =>
    fetch(
      `https://wallwidgy.com/api/wallpapers?color=${color}&count=${countPerColor}`
    ).then(res => res.json())
  );
  
  const results = await Promise.all(promises);
  
  return results.reduce((acc, data, index) => {
    acc[colors[index]] = data.wallpapers;
    return acc;
  }, {});
}

// Usage
const palette = await getColorPalette(['blue', 'green', 'purple'], 3);
console.log(palette);
// {
//   blue: [...3 wallpapers],
//   green: [...3 wallpapers],
//   purple: [...3 wallpapers]
// }

Mood-based wallpaper selector

import requests

MOOD_COLORS = {
    'calm': 'blue',
    'energetic': 'red',
    'natural': 'green',
    'creative': 'purple',
    'minimal': 'black',
    'bright': 'yellow',
    'professional': 'gray'
}

def get_wallpaper_by_mood(mood, device_type='mobile', count=5):
    """Fetch wallpapers based on mood"""
    color = MOOD_COLORS.get(mood.lower())
    
    if not color:
        raise ValueError(f"Unknown mood: {mood}")
    
    response = requests.get(
        'https://wallwidgy.com/api/wallpapers',
        params={
            'color': color,
            'type': device_type,
            'count': count
        }
    )
    
    return response.json()['wallpapers']

# Usage
calm_wallpapers = get_wallpaper_by_mood('calm', device_type='desktop', count=10)
print(f"Got {len(calm_wallpapers)} calm wallpapers")

AMOLED battery saver

import requests

def get_battery_saving_wallpapers(count=5):
    """Fetch black wallpapers optimized for AMOLED screens"""
    response = requests.get(
        'https://wallwidgy.com/api/wallpapers',
        params={
            'color': 'black',
            'category': 'amoled',
            'type': 'mobile',
            'count': count
        }
    )
    
    return response.json()['wallpapers']

# Usage
amoled_wallpapers = get_battery_saving_wallpapers(10)

Color matching tips

Exact color matching

The API looks for exact color name matches in both primary and secondary colors:
# This will match wallpapers with "blue" in primary OR secondary colors
curl "https://wallwidgy.com/api/wallpapers?color=blue"

Color variations

Some colors have variations you can try:
  • Blue: blue, cyan, navy, teal, aqua
  • Red: red, maroon, pink, magenta
  • Green: green, lime, olive, teal
  • Gray: gray, silver, white, black
  • Brown: brown, beige, khaki

Dark theme wallpapers

curl "https://wallwidgy.com/api/wallpapers?color=black&category=minimal&type=mobile&count=5"

Ocean theme wallpapers

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

Forest theme wallpapers

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

Tech aesthetic wallpapers

curl "https://wallwidgy.com/api/wallpapers?color=cyan&category=tech&type=desktop&count=3"

Warm tone wallpapers

curl "https://wallwidgy.com/api/wallpapers?color=orange&category=art&count=5"

Best practices

  1. Use common colors - Stick to basic color names for best results
  2. Combine with categories - Get more specific results by adding category filters
  3. Try variations - If one color doesn’t work, try related colors
  4. Check error messages - The API will tell you if a color has no matches
For AMOLED displays, combine color=black with category=amoled for the best battery-saving wallpapers.
The API searches both primary and secondary colors, so you’ll get wallpapers where your chosen color appears prominently or as an accent.

Build docs developers (and LLMs) love