# Favicon Downloader & Converter — Website icon extractor (`perryay/favicon-downloader-converter`) Actor

Detect, analyze, and download favicons from any website. Scans HTML link tags and standard paths (favicon.ico, favicon.png, apple-touch-icon) to find the best available icon. Supports multi-format detection with size analysis.

- **URL**: https://apify.com/perryay/favicon-downloader-converter.md
- **Developed by:** [Perry AY](https://apify.com/perryay) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / favicon download

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Favicon Downloader & Converter 🎨

**Effortlessly detect, analyze, and download favicons from any website. Scans HTML `<link>` tags and validates 10+ standard favicon paths to find every available icon, then intelligently selects the highest quality candidate for your use case. Supports all major favicon formats — ICO, PNG, SVG, WebP, GIF, and JPEG — with automatic format detection via Content-Type analysis, file size reporting, actionable health recommendations, and batch processing of up to 50 URLs in a single run.**

Built for web developers, brand monitoring teams, CMS integrators, security researchers, and platform engineers who need programmatic access to website favicons at scale. Whether you are populating a dashboard with brand identifiers, enriching bookmark thumbnails, conducting OSINT reconnaissance, or automating client onboarding workflows, this actor delivers production-ready favicon data with zero manual inspection. No browser automation required, no headless dependencies, no manual page-source inspection — just structured, actionable favicon intelligence in seconds.

---

### What does it do?

The **Favicon Downloader & Converter** is a comprehensive favicon intelligence tool that automates what is traditionally a manual, multi-step process. Given one or more website URLs, it systematically discovers every favicon variant associated with each domain and returns structured data you can immediately use in your applications. The actor operates entirely via lightweight HTTP requests — HEAD, GET — with no browser engine, no JavaScript execution, and no heavy dependencies. This makes it fast, resource-efficient, and suitable for high-throughput batch pipelines.

The actor begins by fetching the target page's HTML and parsing all `<link>` elements for `rel="icon"`, `rel="shortcut icon"`, `rel="apple-touch-icon"`, and `rel="apple-touch-icon-precomposed"` attributes — the canonical mechanism by which websites declare their favicons to browsers. Three separate regex patterns cover the full range of HTML attribute orderings (`rel` before `href`, `href` before `rel`, and variants with embedded whitespace), ensuring no malformed markup is missed. It then extends its search beyond the HTML to 10+ well-known standard paths such as `/favicon.ico`, `/favicon.png`, `/favicon.svg`, `/apple-touch-icon.png`, `/favicon-32x32.png`, `/favicon-16x16.png`, `/favicon-192x192.png`, `/favicon-96x96.png`, `/favicon-128.png`, and `/favicon-196x196.png`. This dual-source strategy ensures maximum coverage even when a website's HTML is missing, the favicon is served purely by convention, or the page uses client-side rendering that obscures the `<link>` tag entirely.

Every discovered favicon URL is validated via HTTP HEAD requests to determine its true Content-Type, file size, and accessibility. The actor maps the actual `Content-Type` response header against a comprehensive dictionary of known favicon MIME types: `image/x-icon` and `image/vnd.microsoft.icon` → ICO, `image/png` → PNG, `image/svg+xml` → SVG, `image/webp` → WebP, `image/gif` → GIF, `image/jpeg` and `image/jpg` → JPEG. This means a favicon served at `/favicon.ico` that actually returns a PNG is correctly identified — no assumptions based on file extensions. A smart best-icon selection algorithm then scores each candidate — preferring PNG for broad browser compatibility, then ICO for legacy support, then SVG for scalability — and ranks by file size within each tier to pick the highest-quality representative.

In **full mode** (`mode: "full"`), the actor goes a step further: it downloads the best favicon, stores it persistently in the Apify key-value store with an MD5-based filename for deduplication, and provides a permanent preview URL for direct integration in web pages, dashboards, or APIs. The **download mode** (`mode: "download"`) accepts a raw favicon URL for manual or programmatic downloading. Batch mode processes up to 50 URLs per run and returns aggregate statistics including the number of sites with and without favicons. All modes operate with automatic URL normalisation — missing schemes are prefixed with `https://`, favicon paths are resolved relative to the page origin, and redirect chains are followed transparently.

---

### Who is it for?

| Persona | Typical Need | How the Actor Helps |
|---|---|---|
| **Web Developer** | Fetch client favicons automatically during site setup, CMS onboarding, or domain provisioning | Scans HTML + standard paths, detects all formats, downloads best icon — no manual inspection needed |
| **Brand & Marketing Team** | Monitor favicon consistency across a portfolio of dozens or hundreds of brand domains | Batch mode (up to 50 URLs) with per-domain results; track missing or low-quality favicons via health recommendations |
| **Platform / Product Engineer** | Enrich dashboards, analytics panels, and domain lists with auto-populated favicon thumbnails | Returns structured JSON with `bestFavicon` URL, format, and size; option to download and store permanently to KV store |
| **Security / OSINT Researcher** | Scan domains for favicon presence as part of reconnaissance, threat intel, or brand impersonation investigations | Provides format-verified favicon URLs, file sizes, and Content-Type headers per domain; diagnostics view in dataset |
| **DevOps & Automation Engineer** | Integrate favicon fetching into CI/CD pipelines, monitoring scripts, or data enrichment workflows | Fully scriptable via Apify API; accepts single URL or batch array; deterministic output with MD5-based storage keys |
| **SaaS / Marketplace Operator** | One-click favicon enrichment for user-submitted links, bookmarks, or web properties | Analyze or full mode returns best favicon in a single predictable field; download mode stores to KV for CDN delivery |
| **Content / Editorial Manager** | Ensure bookmark previews and link cards display correctly on internal tools or public platforms | Health recommendations flag missing favicons, undersized icons (< 100 bytes), and suboptimal formats (e.g. ICO where PNG is preferred) |

---

### Why use this?

- **Zero manual inspection** — Automates the tedious process of viewing page source, checking paths, and inspecting formats. One API call replaces minutes of manual work per domain.
- **Dual-source discovery** — Combines HTML `<link>` tag parsing with 10+ hardcoded standard path probes for maximum coverage. Catches favicons even on poorly configured websites.
- **Intelligent best-icon selection** — Prioritises PNG > ICO > SVG > other formats, then ranks by file size within each tier. Returns the single highest-quality candidate rather than overwhelming you with options.
- **Format verification via HEAD requests** — Determines the actual Content-Type of each favicon rather than trusting the file extension. Correctly identifies ICO, PNG, SVG, WebP, GIF, and JPEG regardless of misleading URLs.
- **Actionable health recommendations** — Generates specific, human-readable suggestions when favicons are missing, extremely small (< 100 bytes, likely placeholder or broken), or in suboptimal formats for modern browsers.
- **Batch processing with aggregate statistics** — Analyse up to 50 URLs in a single run with summary counts (sites with favicon vs. without). Ideal for portfolio-wide audits and bulk enrichment.
- **Permanent key-value store integration** — Downloaded favicons are stored with MD5-based filenames for consistent, deduplicated URLs. The returned `previewUrl` is immediately usable in applications.
- **Three flexible operation modes** — Choose `analyze` (discovery only, no download), `download` (fetch a specific URL), or `full` (analyze + download best icon in one pass). No unnecessary overhead.
- **Dataset views for structured analysis** — Three built-in dataset views (`overview`, `diagnostics`, `downloads`) let you explore results at a glance without writing SQL, filtering for missing favicons or download status.
- **Production-grade error handling** — Gracefully handles 404s, timeouts, malformed HTML, redirect chains, and inaccessible paths per URL without failing the entire batch.
- **Lightweight and dependency-free** — No browser engine, no JavaScript runtime, no headless Chrome or Playwright. Pure Python async HTTP with httpx keeps cold starts fast and memory consumption low at just 512 MB.
- **Deterministic output schema** — Every run produces the same JSON structure regardless of mode or batch size. Single-URL mode returns a flat object; batch mode returns a wrapper with `results`, `totalUrls`, and `summary`. Easy to parse in any language.

---

### Features

#### Multi-Source Detection Engine
The actor employs a dual-layer discovery strategy. Layer 1 parses the target page's HTML using three regex patterns to capture `<link>` tags regardless of attribute order (`rel` before `href`, `href` before `rel`, `shortcut icon` variants, `apple-touch-icon` and `apple-touch-icon-precomposed` variants). Layer 2 performs HEAD requests against a curated list of 10+ standard paths, ensuring detection even when the HTML is missing, the favicon is served by convention, or the page uses client-side rendering that obscures the `<link>` tag. Data URIs in `href` attributes are skipped as they are not downloadable.

**Standard paths probed (in order):**
`/favicon.ico`, `/favicon.png`, `/favicon.svg`, `/apple-touch-icon.png`, `/apple-touch-icon-precomposed.png`, `/favicon-32x32.png`, `/favicon-16x16.png`, `/favicon-96x96.png`, `/favicon-128.png`, `/favicon-192x192.png`, `/favicon-196x196.png`

All discovered favicons are deduplicated by URL before being added to the results — if an HTML `<link>` tag and a direct path probe resolve to the same favicon URL (e.g. after redirect normalisation), only one entry is recorded.

#### Format Detection via Content-Type Analysis
Rather than relying on file extensions (which are often absent, wrong, or generic like `.ico` for PNG files), each favicon URL is validated with an HTTP HEAD request. The actor maps the actual `Content-Type` response header against a comprehensive dictionary of known favicon MIME types: `image/x-icon` and `image/vnd.microsoft.icon` → ICO, `image/png` → PNG, `image/svg+xml` → SVG, `image/webp` → WebP, `image/gif` → GIF, `image/jpeg` and `image/jpg` → JPEG. Unrecognised types fall back to the URL's file extension as a last resort.

**MIME type mapping table:**

| Content-Type Header | Detected Format | Notes |
|---|---|---|
| `image/x-icon` | `ico` | Standard ICO format |
| `image/vnd.microsoft.icon` | `ico` | Microsoft variant of ICO |
| `image/png` | `png` | Portable Network Graphics |
| `image/svg+xml` | `svg` | Scalable Vector Graphics |
| `image/webp` | `webp` | WebP format |
| `image/gif` | `gif` | Graphics Interchange Format |
| `image/jpeg` | `jpg` | JPEG / JFIF |
| `image/jpg` | `jpg` | Non-standard variant |
| Anything else | URL extension fallback | Last resort heuristic |

#### Smart Best-Icon Selection Algorithm
When multiple favicons are found (common on modern websites that provide separate icons for different display contexts), the actor applies a deterministic scoring system:

1. **Format priority tier:** PNG (0) > ICO (1) > SVG (2) > all others (3)
2. **Size tiebreaker:** Within the same tier, larger file sizes rank higher (negated for descending sort)
3. **Result:** The top-scored favicon is returned as `bestFavicon` with its URL, detected format, byte size, and human-readable size string

This ensures you always get the most broadly compatible, highest-quality option without manual triage. The rationale for the tier ordering is straightforward: PNG offers universal browser support with lossless compression and full alpha transparency; ICO is the legacy standard that every browser can render but is limited to smaller palettes; SVG provides infinite scalability at small file sizes but is not supported in all contexts (e.g. iOS home screen icons, older email clients); WebP, GIF, and JPEG are ranked lowest because they are either less universally supported (WebP), limited to 256 colours (GIF), or lossy (JPEG).

#### Health Recommendation Engine
The actor generates domain-specific, actionable favicon health recommendations. Four checks are performed per URL:

- **Missing favicon:** If no favicon is found via any source, recommends creating one and adding a `<link>` tag.
- **Suboptimal format:** If the best favicon is not PNG or SVG (e.g. ICO, GIF, JPEG), recommends adding PNG/SVG versions for modern browser support.
- **Undersized icon:** If the best favicon is smaller than 100 bytes, flags it as potentially a placeholder, error page, or broken resource.
- **Missing HTML link tag:** If favicons were found only via direct path probing and not via an HTML `<link>` tag, recommends adding one for optimal browser detection.

Each recommendation is a plain-English string ready for display in dashboards, logs, or automated alerts.

#### Batch Analysis with Aggregate Statistics
When multiple URLs are provided via the `urls` array field, the actor processes each URL independently and returns a structured batch result containing:

- `results` — Array of per-URL analysis objects (same schema as single-URL mode)
- `totalUrls` — Count of URLs received
- `summary` — Aggregate statistics: `sitesWithFavicon` and `sitesWithoutFavicon` counts

This enables portfolio-wide health checks, bulk favicon enrichment, and automated reporting across hundreds of domains.

#### Permanent Key-Value Store Download
In `full` and `download` modes, the actor downloads the selected favicon's binary content and stores it in the Apify key-value store. Each file is named with an MD5 hash of the source URL to guarantee:

- **Deterministic filenames:** Same favicon URL always produces the same storage key
- **Deduplication:** Identical favicons discovered from different sources are stored once
- **Permanent URLs:** The returned `previewUrl` remains valid for the lifecycle of the actor run's default key-value store

The stored content type is set correctly so browsers and CDNs serve the image with the proper MIME type.

#### Three Operation Modes

| Mode | Behaviour | Best For |
|---|---|---|
| `analyze` | Discover, validate, and describe all favicons without downloading any binary data | Audit workflows, health checks, reconnaissance — no storage cost |
| `download` | Accept a specific favicon URL and store it to the key-value store | Manual integration, fetching a known favicon URL programmatically |
| `full` | Analyse the website, select the best favicon, download it, and store the binary | End-to-end enrichment pipelines, one-call favicon acquisition |

#### Dataset Views for Post-Run Analysis
The actor's output dataset includes three pre-built views for exploring results without manual data transformation:

- **Overview:** All URLs with domain, hasFavicon flag, first favicon format/size, best favicon format/size, and recommendations
- **Diagnostics:** Filtered view showing only sites missing favicons, their recommendations, and any fetch errors
- **Download Status:** For full/download runs, shows per-URL download status, HTTP status codes, and stored filenames

#### Graceful Error Handling
Each URL is processed independently. Failures (network timeouts, DNS resolution errors, SSL certificate issues, 404s, malformed HTML) are captured per-URL in the `error` field rather than aborting the entire run. This is critical for batch workflows where a handful of unreachable domains should not block results for the rest of the batch.

---

### Input Parameters

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `mode` | select | `analyze` | No | Operation mode. `analyze` discovers and describes favicons without downloading. `download` fetches a specific favicon URL and stores it to the key-value store. `full` combines analysis and download — discovers all favicons, selects the best one, downloads it, and stores the binary. |
| `url` | string | — | Conditional | Single website URL to analyse (required if `urls` is empty). Accepts URLs with or without a scheme — `https://` is prepended automatically if missing. |
| `urls` | array | `[]` | Conditional | Array of website URLs for batch analysis (maximum 50 entries). Each URL is processed independently. Combine with `url` — both fields are merged into a single deduplicated list before processing. |

**Validation rules:**
- At least one URL must be provided via `url` or `urls`
- Maximum 50 URLs total across both fields — exceeding this limit causes the actor to fail with a descriptive error message
- URLs without a scheme are prefixed with `https://` automatically (http-only sites must specify `http://` explicitly)
- All favicon paths are resolved relative to the provided URL's origin using `urllib.parse.urljoin`
- Mode `analyze` performs HEAD-only requests and does not consume bandwidth for binary downloads
- Mode `download` requires a direct favicon URL (not a page URL) and stores the result to the key-value store
- Mode `full` combines both operations: analysis first, then download of the best candidate

---

### Example Input

#### Single URL — Analyse Only
```json
{
  "url": "https://example.com",
  "mode": "analyze"
}
````

#### Single URL — Analyse + Download Best Favicon

```json
{
  "url": "https://example.com",
  "mode": "full"
}
```

#### Batch Analysis — 3 URLs

```json
{
  "urls": [
    "https://example.com",
    "https://example.com/about",
    "https://example.com/blog"
  ],
  "mode": "analyze"
}
```

#### Direct Favicon Download

```json
{
  "url": "https://example.com/favicon.ico",
  "mode": "download"
}
```

***

### Output Format

#### Single URL — Analyze Mode

```json
{
  "url": "https://example.com",
  "domain": "example.com",
  "hasFavicon": true,
  "favicons": [
    {
      "url": "https://example.com/favicon.ico",
      "format": "ico",
      "contentType": "image/x-icon",
      "sizeBytes": 5430,
      "sizeHuman": "5.3 KB",
      "source": "direct_path"
    },
    {
      "url": "https://example.com/apple-touch-icon.png",
      "format": "png",
      "contentType": "image/png",
      "sizeBytes": 12450,
      "sizeHuman": "12.2 KB",
      "source": "direct_path"
    }
  ],
  "bestFavicon": {
    "url": "https://example.com/apple-touch-icon.png",
    "format": "png",
    "contentType": "image/png",
    "sizeBytes": 12450,
    "sizeHuman": "12.2 KB",
    "source": "direct_path"
  },
  "recommendations": [
    "No <link rel='icon'> tag found. Add one for optimal browser detection."
  ]
}
```

#### Single URL — Full Mode (Analyse + Download)

```json
{
  "url": "https://example.com",
  "domain": "example.com",
  "hasFavicon": true,
  "favicons": [
    {
      "url": "https://example.com/favicon.ico",
      "format": "ico",
      "contentType": "image/x-icon",
      "sizeBytes": 5430,
      "sizeHuman": "5.3 KB",
      "source": "direct_path"
    }
  ],
  "bestFavicon": {
    "url": "https://example.com/favicon.ico",
    "format": "ico",
    "sizeBytes": 5430
  },
  "recommendations": [
    "Best favicon is ICO format. Consider adding PNG/SVG versions for modern browsers."
  ],
  "downloadResult": {
    "url": "https://example.com/favicon.ico",
    "downloaded": true,
    "statusCode": 200,
    "contentType": "image/x-icon",
    "sizeBytes": 5430,
    "sizeHuman": "5.3 KB",
    "storedAs": "favicon-abc123def456.ico",
    "previewUrl": "https://example.com/kv-store/records/favicon-sample.ico"
  },
  "downloadedFavicon": "favicon-abc123def456.ico"
}
```

#### Batch Mode (Multiple URLs)

```json
{
  "results": [
    {
      "url": "https://github.com",
      "domain": "github.com",
      "hasFavicon": true,
      "favicons": [],
      "bestFavicon": {},
      "recommendations": []
    }
  ],
  "totalUrls": 3,
  "summary": {
    "sitesWithFavicon": 2,
    "sitesWithoutFavicon": 1
  }
}
```

#### Output Fields Reference

| Field | Type | Description |
|---|---|---|
| `url` | string | The original input URL (normalised with scheme if needed) |
| `domain` | string | Extracted hostname from the URL (`urlparse(url).netloc`) |
| `hasFavicon` | boolean | `true` if at least one favicon was found via HTML or direct paths |
| `favicons` | array | Array of discovered favicon objects, each with `url`, `format`, `contentType`, `sizeBytes`, `sizeHuman`, and `source` |
| `favicons[].url` | string | Fully qualified favicon URL (may differ from original due to redirects) |
| `favicons[].format` | string | Detected format: `ico`, `png`, `svg`, `webp`, `gif`, `jpg`, or `unknown` |
| `favicons[].contentType` | string | Raw HTTP `Content-Type` header value from the HEAD response |
| `favicons[].sizeBytes` | integer | File size in bytes (from `Content-Length` header, or 0 if unavailable) |
| `favicons[].sizeHuman` | string | Human-readable size string (e.g. `"5.3 KB"`, `"1.2 MB"`) |
| `favicons[].source` | string | Discovery source: `"html_link_tag"` (from `<link>` in HTML) or `"direct_path"` (from standard path probe) |
| `bestFavicon` | object | The single highest-quality favicon per the selection algorithm, or `null` if none found |
| `recommendations` | array of strings | Actionable health suggestions (empty array if no issues detected) |
| `error` | string | Present only if the page could not be fetched; contains the error message |
| `downloadResult` | object | Present in `full` mode; contains download status, stored filename, and preview URL |
| `downloadResult.downloaded` | boolean | Whether the favicon was successfully downloaded |
| `downloadResult.statusCode` | integer | HTTP status code from the download request |
| `downloadResult.storedAs` | string | MD5-based filename in the key-value store |
| `downloadResult.previewUrl` | string | Permanent URL to access the stored favicon via the Apify API |
| `downloadedFavicon` | string | Shorthand for `downloadResult.storedAs` (present in `full` mode) |
| `totalUrls` | integer | Batch mode only: total number of URLs processed |
| `summary.sitesWithFavicon` | integer | Batch mode only: count of URLs where `hasFavicon` is `true` |
| `summary.sitesWithoutFavicon` | integer | Batch mode only: count of URLs where `hasFavicon` is `false` |

***

### Use Cases

- **Web Development & CMS Onboarding** — When provisioning a new client website, dashboard, or CMS tenant, automatically fetch the client's existing favicon as a starting point. The actor's `full` mode returns both the analysis and the stored binary in one call, enabling one-click favicon migration or placeholder setup.

- **Brand Portfolio Monitoring** — Track favicon appearance and format across a portfolio of brand domains. Run weekly batch audits against 50 URLs to detect sites that have lost their favicon, switched to a suboptimal format, or are serving undersized placeholder icons. The health recommendation engine flags each issue with specific, actionable text.

- **Bookmark & Link Enrichment** — Enrich bookmark management tools, link-sharing platforms, or content aggregators with auto-fetched favicon thumbnails. The deterministic MD5-based storage keys ensure that the same favicon URL is never stored twice, and the permanent `previewUrl` is immediately embeddable in HTML `<img>` tags.

- **Dashboard & Analytics Platform Integration** — Auto-populate domain lists, website tiles, and analytics dashboards with their corresponding favicons. The structured JSON output with `bestFavicon` means a single API call provides both the favicon URL and its metadata (format, size) for display logic and caching decisions.

- **Security Reconnaissance & OSINT** — Scan target domains for favicon presence as part of passive reconnaissance. The actor reveals which websites serve favicons, in what format, and from which paths — information that can feed into infrastructure fingerprinting, domain verification, and brand impersonation detection workflows.

- **CI/CD Data Enrichment Pipeline** — Integrate favicon fetching into automated deployment pipelines. When a new customer domain is provisioned, trigger this actor via the Apify API to enrich the customer record with favicon data. The actor's deterministic output (MD5 keys, predictable JSON schema) and batch support make it a natural fit for scripted workflows.

- **Quality Assurance & SEO Auditing** — As part of a broader website quality audit, verify that every domain under management has an appropriately sized favicon in a modern format (PNG or SVG). The actor's health recommendations explicitly flag sites that lack HTML `<link>` tags or serve ICO-only favicons, giving QA teams a clear remediation target.

- **Social Media & Link Preview Enhancement** — Improve link preview quality in social sharing, messaging apps, and embed cards by fetching the best favicon for each URL. The `analyze` mode provides format and size data to ensure the selected icon meets minimum quality thresholds before display.

- **Marketplace & SaaS Multi-Tenant Branding** — For platforms where each tenant or user has a custom domain, automatically populate the favicon for each tenant's branded subdomain or custom domain. Batch mode processes all tenants in a single run, and the key-value store integration serves the stored favicons directly.

- **Internal Tooling & Admin Panel Enrichment** — Enrich internal admin panels, monitoring dashboards, and operational tools with visual domain identifiers. The actor's simple API contract (URL in → structured JSON out) makes it trivial to integrate with any backend, from Python scripts to Node.js microservices to spreadsheet automation.

- **Domain Portfolio Acquisition Screening** — When evaluating a domain portfolio for acquisition, quickly assess which domains have professionally maintained favicons (PNG/SVG, proper size, HTML link tags present) versus neglected ones with missing or broken icons. The batch output's `summary.sitesWithoutFavicon` count gives an immediate quality signal.

- **Email Signature & Template Automation** — Populate email signatures, newsletter templates, and branded correspondence with the sending domain's favicon as a visual trust signal. The deterministic preview URL from the key-value store means the same favicon can be embedded across hundreds of templates without per-template upload.

- **Favicon Migration & CDN Pre-Seeding** — When migrating a website to a new platform or CDN, use the actor to discover all existing favicon paths and formats, download the best icon, and re-host it on your own infrastructure. The `download` mode makes this a single API call per domain.

- **Competitive Brand Analysis** — Monitor how competitors present their brand identity through favicons. Batch-analyse competitor domains weekly to detect format changes (e.g. ICO → SVG), new apple-touch-icon variants, or favicon drops that may signal rebranding or domain neglect.

- **Multi-Language & Subdomain Auditing** — Audit favicon consistency across subdomains (en.example.com, de.example.com, fr.example.com) and language variants. Use batch mode to process all variants in one run and compare their `bestFavicon` results for discrepancies in format, size, or presence.

- **Reseller & White-Label Platform Onboarding** — For platforms where resellers or white-label partners bring their own domains, automate favicon detection as part of the onboarding workflow. The `full` mode stores the favicon to a key-value store immediately, ready for display on the partner's dashboard without additional processing.

# Actor input Schema

## `mode` (type: `string`):

'analyze' (find and describe favicons), 'download' (download a specific favicon URL), 'full' (analyze + download best favicon)

## `url` (type: `string`):

A single website URL to analyze for favicons.

## `urls` (type: `array`):

Array of website URLs for batch favicon analysis (max 50).

## Actor input object example

```json
{
  "mode": "analyze",
  "url": "https://example.com",
  "urls": [
    "https://example.com",
    "https://github.com"
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Favicon analysis results — one item per URL analyzed

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "url": "https://example.com",
    "urls": [
        "https://example.com",
        "https://github.com"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("perryay/favicon-downloader-converter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "url": "https://example.com",
    "urls": [
        "https://example.com",
        "https://github.com",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("perryay/favicon-downloader-converter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "url": "https://example.com",
  "urls": [
    "https://example.com",
    "https://github.com"
  ]
}' |
apify call perryay/favicon-downloader-converter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=perryay/favicon-downloader-converter",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Favicon Downloader & Converter — Website icon extractor",
        "description": "Detect, analyze, and download favicons from any website. Scans HTML link tags and standard paths (favicon.ico, favicon.png, apple-touch-icon) to find the best available icon. Supports multi-format detection with size analysis.",
        "version": "1.0",
        "x-build-id": "GiwfzgqufnbhNKxPu"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/perryay~favicon-downloader-converter/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-perryay-favicon-downloader-converter",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/perryay~favicon-downloader-converter/runs": {
            "post": {
                "operationId": "runs-sync-perryay-favicon-downloader-converter",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/perryay~favicon-downloader-converter/run-sync": {
            "post": {
                "operationId": "run-sync-perryay-favicon-downloader-converter",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "mode": {
                        "title": "Operation Mode",
                        "enum": [
                            "analyze",
                            "download",
                            "full"
                        ],
                        "type": "string",
                        "description": "'analyze' (find and describe favicons), 'download' (download a specific favicon URL), 'full' (analyze + download best favicon)",
                        "default": "analyze"
                    },
                    "url": {
                        "title": "Single URL",
                        "type": "string",
                        "description": "A single website URL to analyze for favicons."
                    },
                    "urls": {
                        "title": "Multiple URLs",
                        "type": "array",
                        "description": "Array of website URLs for batch favicon analysis (max 50).",
                        "default": []
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```