Skip to main content

​
GET /api/wallpapers/search

Search for wallpapers using text-based queries. This endpoint allows you to find wallpapers by searching through their metadata, tags, and descriptions.
This endpoint is currently under development. The route file exists but has no implementation yet. Check back later for full search functionality.

​
Planned features

When implemented, this endpoint will support:

​
Query parameters

​
q
string
required
Search query string. Will search through wallpaper names, tags, categories, and descriptions.
​
type
string
Filter search results by device type (desktop or mobile)
​
category
string
Filter search results by category
​
limit
number
default:"20"
Maximum number of results to return
​
offset
number
default:"0"
Number of results to skip (for pagination)

​
Expected response format

​
results
array
Array of matching wallpapers
​
[].public_id
string
Unique identifier for the wallpaper
​
[].name
string
Name of the wallpaper
​
[].url
string
URL to the wallpaper image
​
[].category
string
Category the wallpaper belongs to
​
[].tags
array
Tags associated with the wallpaper
​
[].relevance
number
Relevance score (0-1) indicating how well the wallpaper matches the query
​
total
number
Total number of results matching the query
​
limit
number
Maximum number of results per page
​
offset
number
Current offset in the result set

​
Alternative endpoints

Until search is implemented, you can use these alternative approaches:

​
Filter by category

Use the /api/wallpapers endpoint with the category parameter: 
curl "https://wallwidgy.com/api/wallpapers?category=nature&count=10"

​
Filter by color

Use the /api/wallpapers endpoint with the color parameter: 
curl "https://wallwidgy.com/api/wallpapers?color=blue&count=10"

​
Combine filters

Combine multiple filters to narrow down results: 
curl "https://wallwidgy.com/api/wallpapers?category=space&color=blue&type=desktop&count=5"

​
Example usage (planned)

Once implemented, you’ll be able to search like this: 
# Basic search
curl "https://wallwidgy.com/api/wallpapers/search?q=mountain"

# Search with type filter
curl "https://wallwidgy.com/api/wallpapers/search?q=sunset&type=desktop"

# Search with pagination
curl "https://wallwidgy.com/api/wallpapers/search?q=ocean&limit=10&offset=20"

# Search with multiple filters
curl "https://wallwidgy.com/api/wallpapers/search?q=nature&type=mobile&category=landscape&limit=5"

​
Example response (planned)

{
  "results": [
    {
      "public_id": "wallpapers/mountain_sunset_4k",
      "name": "mountain_sunset_4k",
      "url": "https://wallwidgy.com/wallpapers/mountain_sunset_4k.jpg",
      "category": "nature",
      "tags": ["mountain", "sunset", "landscape", "desktop"],
      "relevance": 0.95
    },
    {
      "public_id": "wallpapers/mountain_lake_morning",
      "name": "mountain_lake_morning",
      "url": "https://wallwidgy.com/wallpapers/mountain_lake_morning.jpg",
      "category": "nature",
      "tags": ["mountain", "lake", "morning", "desktop"],
      "relevance": 0.87
    }
  ],
  "total": 45,
  "limit": 20,
  "offset": 0
}

​
Implementation status

The search endpoint route file exists at /api/wallpapers/search/route.ts but is currently empty. We’re working on implementing comprehensive search functionality that will include:
  • Full-text search across wallpaper metadata
  • Fuzzy matching for typo tolerance
  • Relevance scoring
  • Search result ranking
  • Search suggestions and autocomplete
  • Advanced filtering and sorting options
Check the GitHub repository for updates on search implementation progress.

Build docs developers (and LLMs) love

Get started for freeTalk to us