Icon Search API Documentation
Semantic search for React Icons using vector embeddings and AI-powered matching
📖 Read the complete API guide→How It Works
Semantic Vector Search
Our icon search uses advanced vector embeddings to understand the semantic meaning of your queries, not just keyword matching. This means you can describe what you need in natural language, and we'll find the most relevant icons.
Query Processing
Your search query is converted into a high-dimensional vector using AI models (Qwen2.5 or OpenAI). We expand your query with semantic context and synonyms to capture the full meaning.
Vector Similarity
We compare your query vector against pre-computed embeddings for 13,000+ icons from multiple libraries. Using cosine similarity, we find icons that are semantically similar to your query.
Ranking & Results
Results are ranked by relevance score and filtered by your selected icon libraries. We return the most relevant icons with their metadata, import paths, and similarity scores.
Supported Icon Libraries
API Endpoints
POST /api/icons/search
Search for a single icon
// Single icon search
const ICON_SEARCH_API_URL = process.env.NEXT_PUBLIC_ICON_SEARCH_API_URL || 'https://icon-search-service.vercel.app';
const response = await fetch(`${ICON_SEARCH_API_URL}/api/icons/search`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
query: 'user profile',
limit: 10,
libraries: ['hi', 'hi2', 'bs', 'fi', 'lu', 'md'] // Optional: filter by libraries
})
});
const data = await response.json();
console.log(data.results); // Array of icon resultsquery(string, required) - Search querylimit(number, optional) - Max results (default: 20, max: 50)libraries(string[], optional) - Filter by library codes
{
"results": [
{
"id": "hi-HiUser",
"name": "HiUser",
"library": "hi",
"libraryName": "Heroicons",
"description": "...",
"keywords": ["user", "person", ...],
"score": 0.92,
"importPath": "react-icons/hi"
}
],
"count": 10,
"query": "user profile"
}POST /api/icons/search-batch
Search for multiple icons in one request
// Batch search (multiple queries)
const ICON_SEARCH_API_URL = process.env.NEXT_PUBLIC_ICON_SEARCH_API_URL || 'https://icon-search-service.vercel.app';
const response = await fetch(ICON_SEARCH_API_URL + '/api/icons/search-batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
queries: [
'shopping cart',
'email notification',
'settings gear'
],
limit: 1, // Icons per query
libraries: ['hi', 'hi2'] // Optional
})
});
const data = await response.json();
// data.results is an array of { query, icons, count }queries(string[], required) - Array of search querieslimit(number, optional) - Icons per query (default: 1, max: 50)libraries(string[], optional) - Filter by library codes
Rate Limits & Pricing
Free Tier
- 100 requests per hour per IP address
- Access to all free icon libraries
- Perfect for personal projects and production applications
- No API key required
Commercial Tier
- Unlimited requests with API key
- Access to all icon libraries including premium
- Priority support and SLA guarantees
- Custom pricing based on usage
Rate Limit Exceeded?
When you exceed 100 requests per hour, you'll receive a 429 status code. The limit resets automatically. For commercial use, please sign up for API access below or book a call to discuss your needs.
Authentication
For the free tier, no authentication is required. Requests are rate-limited by IP address.
For commercial access, include your API key in the Authorization header:
# Using cURL
curl -X POST https://icon-search-service.vercel.app/api/icons/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"query": "user profile",
"limit": 10
}'Request API Access
Need help? Contact support