# Favicon API

Favicon API is a high-performance service for fetching and processing website favicons.

## Overview

The Favicon API provides a simple REST interface to fetch favicons from any website. It supports multiple image formats, resizing, and intelligent fallback mechanisms.

## Base URL

Production: http://favicon.btoven.net

## Endpoints

### Get Favicon
GET /:domain

Fetches the favicon for the specified domain.

**Path Parameters:**
- `domain` - The domain name (e.g., google.com, example.com)

**Query Parameters:**
- `size` - Image size in pixels (e.g., 16, 32, 64, 128, 256)
- `format` - Output format: png, jpg, webp, ico, svg
- `response` - Response type: image (default) or json
- `default` - Fallback image URL when favicon not found

**Examples:**
- `GET /google.com` - Returns Google's favicon (default size/format)
- `GET /example.com?size=64&format=png` - Returns 64x64 PNG favicon
- `GET /github.com?response=json` - Returns JSON with metadata

### Health Check
GET /health

Returns service health status.

## Response Formats

### Image Response (default)
- Content-Type: image/png, image/jpeg, image/webp, image/x-icon, or image/svg+xml
- Cache headers: Configurable (default 7 days)

### JSON Response
```json
{
  "url": "http://favicon.btoven.net/google.com?size=128",
  "sourceUrl": "https://www.google.com/favicon.ico",
  "width": 128,
  "height": 128,
  "format": "png",
  "bytes": 2048,
  "source": "html"
}
```

## Features

- **Smart Discovery**: Automatically finds the best favicon from HTML, manifest, and known paths
- **Image Processing**: Resize and convert images on-the-fly using Sharp
- **Fallback Support**: Optional fallback to Google's favicon API
- **Caching**: HTTP cache headers for CDN/proxy integration
- **Security**: Blocks private IPs and detects crawler/scanner requests
- **Analytics**: Built-in request logging and analytics support

## Technology Stack

- **Runtime**: Bun
- **Framework**: Hono
- **Image Processing**: Sharp (libvips)
- **Validation**: Zod
- **Container**: Docker (Alpine Linux)

## Rate Limits

- No hard rate limits implemented
- Configurable request timeout (default 5 seconds)
- Max image size: 5MB

## Usage Examples

### HTML
```html
<img src="http://favicon.btoven.net/google.com" alt="Google Favicon">
<img src="http://favicon.btoven.net/twitter.com?size=32" alt="Twitter Favicon">
```

### JavaScript
```javascript
const response = await fetch('http://favicon.btoven.net/example.com?response=json');
const data = await response.json();
console.log(data.url); // Image URL
```

### cURL
```bash
curl "http://favicon.btoven.net/google.com?size=128&format=png" -o favicon.png
```

## Error Handling

- `400 Bad Request`: Invalid parameters or crawler detected
- `500 Internal Server Error`: Processing error
- `404 Not Found`: Page not found (web UI only)

## Documentation

Full documentation available at: http://favicon.btoven.net/docs

## Support

Developed by Btoven.net
GitHub: https://github.com/vemetric/favicon-api