Overview
The WallWidgy API automatically categorizes wallpapers by orientation, making it easy to fetch wallpapers optimized for specific devices. Use the type query parameter to filter by desktop or mobile.
Supported device types
The API supports two device types based on image orientation:
desktop - Landscape/horizontal wallpapers (wider than tall)mobile - Portrait/vertical wallpapers (taller than wide)
How device detection works
Wallpapers are categorized by their orientation in the metadata:
- Desktop:
orientation: "Desktop" - Landscape images optimized for monitors, laptops, and wide screens
- Mobile:
orientation: "Mobile" - Portrait images optimized for phones and tablets
Basic usage
Get mobile wallpapers
curl "https://wallwidgy.com/api/wallpapers?type=mobile"
Get desktop wallpapers
curl "https://wallwidgy.com/api/wallpapers?type=desktop"
{
"wallpapers": [
"https://wallwidgy.com/wallpapers/wallpapers_mobile_001.webp"
],
"count": 1,
"category": "all",
"type": "mobile",
"color": "all"
}
Combining with other filters
Device type + category
Get mobile anime wallpapers:
curl "https://wallwidgy.com/api/wallpapers?type=mobile&category=anime"
Device type + color
Get desktop wallpapers with blue tones:
curl "https://wallwidgy.com/api/wallpapers?type=desktop&color=blue"
Device type + category + color
Get mobile nature wallpapers with green tones:
curl "https://wallwidgy.com/api/wallpapers?type=mobile&category=nature&color=green"
Multiple wallpapers
Fetch multiple wallpapers of the same device type:
curl "https://wallwidgy.com/api/wallpapers?type=mobile&count=5"
Practical examples
Responsive wallpaper picker
Detect device type and fetch appropriate wallpapers:
function isMobileDevice() {
return /Android|iPhone|iPad|iPod/i.test(navigator.userAgent) ||
window.innerWidth < 768;
}
async function fetchWallpaperForDevice() {
const deviceType = isMobileDevice() ? 'mobile' : 'desktop';
const response = await fetch(
`https://wallwidgy.com/api/wallpapers?type=${deviceType}&count=3`
);
const data = await response.json();
return data.wallpapers;
}
// Usage
const wallpapers = await fetchWallpaperForDevice();
console.log(wallpapers);
import platform
import requests
def get_platform_wallpapers(count=5):
# Determine platform
system = platform.system()
device_type = 'mobile' if system in ['Android', 'iOS'] else 'desktop'
response = requests.get(
'https://wallwidgy.com/api/wallpapers',
params={'type': device_type, 'count': count}
)
return response.json()['wallpapers']
# Usage
wallpapers = get_platform_wallpapers(count=10)
print(f"Got {len(wallpapers)} {device_type} wallpapers")
Fallback behavior
If no wallpapers match the device type filter (combined with other filters), the API automatically falls back to showing all device types that match the remaining filters.
# If no mobile nature wallpapers exist
curl "https://wallwidgy.com/api/wallpapers?type=mobile&category=nature"
# The API will return desktop nature wallpapers as a fallback
Common use cases
Mobile app wallpaper feature
// React Native example
import { Dimensions } from 'react-native';
const { width, height } = Dimensions.get('window');
const isPortrait = height > width;
const deviceType = isPortrait ? 'mobile' : 'desktop';
const fetchWallpapers = async () => {
const response = await fetch(
`https://wallwidgy.com/api/wallpapers?type=${deviceType}&count=10`
);
return await response.json();
};
Desktop wallpaper rotator
import requests
import time
import os
def rotate_desktop_wallpaper(interval_seconds=3600):
"""Change desktop wallpaper every hour"""
while True:
response = requests.get(
'https://wallwidgy.com/api/wallpapers',
params={'type': 'desktop', 'count': 1}
)
wallpaper_url = response.json()['wallpapers'][0]
# Download and set as wallpaper
# (implementation depends on OS)
time.sleep(interval_seconds)
Best practices
- Auto-detect device type - Use device detection logic to automatically request the right type
- Combine with categories - Get device-specific wallpapers in user’s favorite category
- Request multiple wallpapers - Fetch several at once to reduce API calls
- Handle fallbacks - Be prepared to receive any device type if filters are too restrictive
For the best user experience, combine device type filtering with category preferences. For example: type=mobile&category=anime&count=10