FaviSnap API Documentation

Extract favicons from any website URL and resize them to any dimension (16-512px). Convert between PNG, ICO, and WebP formats. The API automatically detects favicons from link tags, Apple touch icons, manifest.json files, and generates fallback icons when none exist.

Base URL: https://favisnap.dev/api/v1

Authentication

No authentication is required. The API is free and open for everyone. Simply make HTTP requests to the endpoints below.

GET /icon/:domain

CDN-style direct favicon proxy. Returns the raw image — use directly in <img> tags. This is the simplest way to use FaviSnap.

Usage

          
          HTML
        
<!-- Just use the URL as an image source — that's it! -->
<img src="https://softvoyagers-favisnap.azurewebsites.net/icon/github.com" alt="GitHub favicon">

<!-- With size parameter -->
<img src="https://softvoyagers-favisnap.azurewebsites.net/icon/stackoverflow.com?size=64" alt="SO favicon">

<!-- WebP format for smaller file size -->
<img src="https://softvoyagers-favisnap.azurewebsites.net/icon/google.com?size=32&format=webp" alt="Google favicon">

Query Parameters

Param	Type	Required	Description
`size`	number	optional	Target size in pixels (16-512, default: 32)
`format`	string	optional	Output format: `png`, `webp` (default: png)

Pro tip: The /icon/:domain endpoint is the fastest way to add favicons to your app. Responses are cached for 7 days and served with proper Cache-Control headers.

GET /favicon

GET /api/v1/favicon

Extract and resize a favicon from a single website URL. Returns a base64-encoded data URI ready for use in <img> tags or saving to a database.

Query Parameters

Param	Type	Required	Description
`url`	string	required	The website URL to extract favicon from (must be a valid HTTP/HTTPS URL)
`size`	number	optional	Target size in pixels (16-512, default: 32)
`format`	string	optional	Output format: `png`, `ico`, `webp` (default: png)

Example Request

          
          cURL
        
curl "https://favisnap.dev/api/v1/favicon?url=https://github.com&size=64&format=png"

Example Response

          
          
          
          JSON Response (200 OK)
        
{
  "status": "success",
  "data": {
    "url": "https://github.com",
    "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 2048,
    "format": "png",
    "dimensions": {
      "width": 64,
      "height": 64
    }
  }
}

GET /favicon/image

GET /api/v1/favicon/image

Same as GET /favicon but returns the raw image instead of JSON. Use this when you need full URL control (the /icon/:domain shortcut always uses HTTPS).

Example

          
          HTML
        
<img src="https://softvoyagers-favisnap.azurewebsites.net/api/v1/favicon/image?url=https://github.com&size=64">

POST /favicon/batch

POST /api/v1/favicon/batch

Extract favicons from multiple URLs in one request. Returns an array of results. Maximum 10 URLs per request.

Query Parameters

Param	Type	Required	Description
`size`	number	optional	Target size in pixels (16-512, default: 32) — applies to all URLs
`format`	string	optional	Output format: `png`, `ico`, `webp` (default: png) — applies to all URLs

Request Body

Field	Type	Required	Description
`urls`	string[]	required	Array of website URLs (max 10)

Example Request

          
          
          
          cURL
        
curl -X POST "https://favisnap.dev/api/v1/favicon/batch?size=32&format=png" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://github.com",
      "https://stackoverflow.com",
      "https://developer.mozilla.org"
    ]
  }'

Example Response

          
          
          
          JSON Response (200 OK)
        
{
  "status": "success",
  "data": {
    "count": 3,
    "results": [
      {
        "url": "https://github.com",
        "favicon": "data:image/png;base64,iVBORw0KG...",
        "size": 1024,
        "format": "png",
        "dimensions": { "width": 32, "height": 32 },
        "error": null
      },
      {
        "url": "https://stackoverflow.com",
        "favicon": "data:image/png;base64,iVBORw0KG...",
        "size": 1156,
        "format": "png",
        "dimensions": { "width": 32, "height": 32 },
        "error": null
      },
      {
        "url": "https://developer.mozilla.org",
        "favicon": "data:image/png;base64,iVBORw0KG...",
        "size": 980,
        "format": "png",
        "dimensions": { "width": 32, "height": 32 },
        "error": null
      }
    ]
  }
}

URL Parameter

The url parameter must be a valid HTTP or HTTPS URL pointing to a website. The API will:

Fetch the HTML page at the URL
Look for favicon link tags (<link rel="icon">, <link rel="apple-touch-icon">, etc.)
Check manifest.json if present
Try the default /favicon.ico path
Generate a fallback icon from domain initials if no favicon found

SSRF Protection: The API blocks requests to private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) to prevent server-side request forgery attacks.

Size Parameter

The size parameter controls the output dimensions. Valid range: 16-512 pixels. Default: 32.

Common sizes:

16 — Classic browser tab icon
32 — Standard favicon (default)
64 — High-DPI displays
128 — Large icons for bookmarks
256 — macOS dock icons

Format Parameter

The format parameter controls the output image format. Valid options: png, ico, webp. Default: png.

Format	MIME Type	Use Case
`png`	image/png	Best quality, broad support (default)
webp	image/webp	Smallest file size, modern browsers
ico	image/png	Legacy favicon format (returned as PNG)

Response Format

All responses are JSON. Successful responses include "status": "success" and a "data" object. Error responses include "error" and "message" fields.

Success Response Fields

Field	Type	Description
`status`	string	Always "success" for successful requests
`data.url`	string	The original URL that was processed
`data.favicon`	string	Base64-encoded data URI (e.g., "data:image/png;base64,...")
`data.size`	number	File size in bytes
`data.format`	string	Image format (png, webp, or png for ico)
`data.dimensions`	object	Width and height in pixels

Error Response

          
          400 Bad Request
        
{
  "error": "Invalid URL",
  "message": "The 'url' parameter must be a valid HTTP or HTTPS URL"
}

Error Codes

Status	Meaning
`400`	Bad Request — Missing/invalid URL, size out of range (16-512), or unsupported format
`403`	Forbidden — SSRF protection blocked private IP, localhost, or internal network
`404`	Not Found — Endpoint does not exist
`429`	Too Many Requests — Rate limit exceeded (60 req/min)
`500`	Internal Server Error — Favicon extraction failed or server error

Rate Limits

The API applies rate limiting to protect service quality:

Limit	Value
Requests per minute	`60` per IP address
Window	`60 seconds` sliding window

When rate limited, the API returns a 429 status with a Retry-After header.

Rate limit headers are included in every response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Caching

All successful responses include cache headers for 7 days:

Cache-Control: public, max-age=604800, immutable
X-Favicon-Size — Dimensions (e.g., "32x32")
X-Favicon-Format — Image format (png, webp)

Browsers and CDNs will cache responses, reducing load times and API calls for repeat requests.

cURL Example

          
          
          
          terminal
        
# Extract a single favicon (32x32 PNG)
curl "https://favisnap.dev/api/v1/favicon?url=https://github.com&size=32&format=png"

# Extract in WebP format (smaller file size)
curl "https://favisnap.dev/api/v1/favicon?url=https://stackoverflow.com&size=64&format=webp"

# Batch request (multiple URLs)
curl -X POST "https://favisnap.dev/api/v1/favicon/batch?size=32&format=png" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://github.com", "https://stackoverflow.com"]}'

JavaScript Example

          
          
          
          app.js
        
// Extract a single favicon
const response = await fetch(
  'https://favisnap.dev/api/v1/favicon?url=https://github.com&size=64&format=png'
);
const data = await response.json();

if (data.status === 'success') {
  // Use the base64 data URI directly in an img tag
  const img = document.createElement('img');
  img.src = data.data.favicon;
  img.alt = `Favicon for ${data.data.url}`;
  document.body.appendChild(img);
}

// Batch request (multiple URLs)
const batchResponse = await fetch(
  'https://favisnap.dev/api/v1/favicon/batch?size=32&format=png',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      urls: ['https://github.com', 'https://stackoverflow.com']
    })
  }
);
const batchData = await batchResponse.json();
console.log(`Extracted ${batchData.data.count} favicons`);

Python Example

          
          
          
          main.py
        
import requests
import base64

# Extract a single favicon
response = requests.get(
    'https://favisnap.dev/api/v1/favicon',
    params={'url': 'https://github.com', 'size': 128, 'format': 'png'}
)
data = response.json()

if data['status'] == 'success':
    # Save the favicon to a file
    favicon_base64 = data['data']['favicon'].split(',')[1]
    with open('github_favicon.png', 'wb') as f:
        f.write(base64.b64decode(favicon_base64))
    print(f"Saved favicon ({data['data']['dimensions']['width']}x{data['data']['dimensions']['height']})")

# Batch request (multiple URLs)
batch_response = requests.post(
    'https://favisnap.dev/api/v1/favicon/batch',
    params={'size': 32, 'format': 'png'},
    json={'urls': ['https://github.com', 'https://stackoverflow.com']}
)
batch_data = batch_response.json()
print(f"Extracted {batch_data['data']['count']} favicons")