Icon Search API - Integrate Semantic Icon Search into Your Applications

Our Icon Search API provides programmatic access to our semantic icon search engine, allowing you to integrate intelligent icon discovery into your applications, design tools, code editors, or any service that needs to help users find icons.

Overview

The API uses the same powerful semantic search technology as our web interface, powered by vector embeddings and AI. You can search for icons using natural language queries and get results with similarity scores, metadata, and import paths.

API Endpoints

Single Icon Search

Endpoint: POST /api/icons/search

Search for icons matching a single query.

Request Body:

{
  "query": "user profile settings",
  "limit": 10,
  "libraries": ["hi", "hi2", "bs", "fi", "lu", "md"]
}

Response:

{
  "results": [
    {
      "id": "hi-user-circle",
      "name": "UserCircle",
      "library": "hi",
      "libraryName": "Heroicons",
      "description": "User profile circle icon",
      "keywords": ["user", "profile", "account", "person"],
      "score": 0.92,
      "importPath": "react-icons/hi"
    }
  ],
  "count": 1,
  "query": "user profile settings"
}

Batch Icon Search

Endpoint: POST /api/icons/search-batch

Search for icons matching multiple queries in a single request.

Request Body:

{
  "queries": [
    "shopping cart",
    "email notification",
    "settings gear"
  ],
  "limit": 1,
  "libraries": ["hi", "hi2"]
}

Response:

{
  "results": [
    {
      "query": "shopping cart",
      "icons": [...],
      "count": 1
    },
    {
      "query": "email notification",
      "icons": [...],
      "count": 1
    },
    {
      "query": "settings gear",
      "icons": [...],
      "count": 1
    }
  ],
  "totalQueries": 3
}

Code Examples

JavaScript/TypeScript

// Single search
const response = await fetch('https://api.technigami.com/api/icons/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY' // Required for commercial tier
  },
  body: JSON.stringify({
    query: 'user profile',
    limit: 10,
    libraries: ['hi', 'hi2', 'bs', 'fi', 'lu', 'md']
  })
});

const data = await response.json();
console.log(data.results);

Python

import requests

response = requests.post(
    'https://api.technigami.com/api/icons/search',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    json={
        'query': 'user profile',
        'limit': 10,
        'libraries': ['hi', 'hi2', 'bs', 'fi', 'lu', 'md']
    }
)

data = response.json()
print(data['results'])

cURL

curl -X POST https://api.technigami.com/api/icons/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "user profile",
    "limit": 10,
    "libraries": ["hi", "hi2", "bs", "fi", "lu", "md"]
  }'

Authentication

Free Tier

No authentication required. Rate limited to 100 requests per hour per IP address.

Commercial Tier

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Contact us to get an API key and discuss pricing for higher volume usage.

Rate Limits

• Free Tier: 100 requests per hour per IP address
• Commercial Tier: Custom limits based on your plan

When rate limited, you'll receive a 429 Too Many Requests response with details about when you can make more requests.

Response Format

Single Search Response

interface SearchResponse {
  results: IconResult[];
  count: number;
  query: string;
}

interface IconResult {
  id: string;
  name: string;
  library: string;
  libraryName: string;
  description: string;
  keywords: string[];
  score: number; // Similarity score (0-1
  importPath: string; // e.g., "react-icons/hi"
}

Batch Search Response

interface BatchSearchResponse {
  results: Array<{
    query: string;
    icons: IconResult[];
    count: number;
  }>;
  totalQueries: number;
}

Error Handling

The API returns standard HTTP status codes:

• 200 OK: Successful request
• 400 Bad Request: Invalid request body or parameters
• 401 Unauthorized: Missing or invalid API key (commercial tier)
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Error responses include a message:

{
  "error": "Rate limit exceeded. Please try again later.",
  "retryAfter": 3600
}

Use Cases

1. Design Tools

Integrate icon search into Figma plugins, Sketch extensions, or Adobe XD plugins to help designers find icons without leaving their design environment.

2. Code Editors

Build VS Code extensions or IDE plugins that suggest icons as developers type feature descriptions.

3. Content Management Systems

Help content editors find appropriate icons when creating pages or posts.

4. Documentation Tools

Automatically suggest icons for documentation based on section content.

5. AI Assistants

Enable AI coding assistants to find and suggest icons based on natural language descriptions.

Best Practices

1. Cache Results: Icon libraries don't change frequently, so cache results when possible
2. Use Batch API: When searching for multiple icons, use the batch endpoint for better performance
3. Filter Libraries: Specify libraries to reduce response size and improve relevance
4. Handle Rate Limits: Implement exponential backoff when rate limited
5. Validate Input: Ensure queries are meaningful and not empty

Library Codes

Available library codes for filtering:

• hi - Heroicons
• hi2 - Heroicons 2
• bs - Bootstrap Icons
• fi - Feather Icons
• lu - Lucide Icons
• md - Material Design Icons
• fa - Font Awesome 5 (premium)
• fa6 - Font Awesome 6 (premium)

Getting Started

1. Try the Free Tier: Start with the free tier (no API key needed) to test integration
2. Sign Up: Fill out our API signup form for commercial access
3. Get Your API Key: We'll provide your API key and documentation
4. Integrate: Use the code examples above to integrate into your application

Support

For API support, questions, or to discuss custom integration needs:

• Visit our API Documentation Page
• Contact us through our Contact Form
• Check our blog for updates and tutorials

Related Resources

• Semantic Icon Search - Web interface for icon search
• Icon Search from Paragraphs - Find multiple icons from descriptions
• Website Audit Tool - Analyze your website

---

Ready to integrate semantic icon search into your application? Visit our API Documentation Page to get started.