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"
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
Popular color combinations
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
Use common colors - Stick to basic color names for best results
Combine with categories - Get more specific results by adding category filters
Try variations - If one color doesn’t work, try related colors
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.