Перейти к содержимому
Favicon.is

Документация API

Favicon.is — простой HTTP API, который возвращает фавикон любого сайта в виде изображения. Никаких ключей, SDK и заголовков с лимитами, за которыми нужно следить.

Эндпоинт

Отправьте GET-запрос, указав домен в пути. Тело ответа — это само изображение, поэтому URL можно использовать прямо в теге <img>.

GEThttps://favicon.is/{domain}
Пример
<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">
GitHub faviconGitHub favicon (256 px)

Параметры запроса

ПараметрТипПо умолчаниюОписание
sizeinteger128Размер иконки в пикселях: 16, 32, 48, 64, 128 или 256. Другие значения округляются до ближайшего поддерживаемого размера.?size=64
largerbooleanfalseВернуть иконку в высоком разрешении (256 px). То же самое, что size=256.?larger=true
originalbooleanfalseПропустить кэш фавиконов Google и взять иконку, объявленную в HTML самого сайта.?original=true
downloadbooleanfalseОтправить заголовок Content-Disposition, чтобы браузер скачал иконку как файл.?download=1

Допустимый ввод

Можно передать просто домен, поддомен, полный URL или интернационализированное доменное имя. Протокол, www., порт, путь и строка запроса удаляются автоматически, а регистр букв в домене не учитывается.

Пример
https://favicon.is/github.com
https://favicon.is/docs.github.com
https://favicon.is/https://github.com/features/actions
https://favicon.is/WWW.GitHub.com:443
https://favicon.is/bücher.de
https://favicon.is/例子.中国

Проверка доменов по списку TLD IANA

Favicon.is загружает иконки только для доменов, суффикс которых — домен верхнего уровня (TLD), делегированный в базе корневой зоны IANA. На запросы с другими суффиксами, например .local, .test или с опечатками, сразу возвращается иконка по умолчанию — без обращения к какому-либо серверу.

Все поддерживаемые TLD

Ответ

Успешный запрос возвращает HTTP 200 с изображением (обычно PNG, иногда ICO или SVG). Если иконку найти не удалось, вы всё равно получите HTTP 200 с иконкой по умолчанию, так что на вашей странице никогда не будет битого изображения.

cURL
$ curl -I https://favicon.is/github.com

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, stale-while-revalidate=604800
access-control-allow-origin: *
etag: "8c1f3b6a2d4e5f60718293a4"
x-source: cache-r2
x-response-time: 3ms

Заголовки ответа

Content-Type
Формат изображения: image/png, image/x-icon, image/svg+xml, image/jpeg, image/gif или image/webp.
Cache-Control
Браузеры и CDN могут кэшировать иконки на сутки и перепроверять их в фоне в течение недели.
X-Source
Откуда взята иконка: cache-edge, cache-r2, google, live или default.
X-Reason
Только для иконки по умолчанию. Объясняет причину: invalid-domain, unsupported-tld, not-found или failure-cache.
X-Response-Time
Сколько времени обработка запроса заняла на нашей стороне.
Access-Control-Allow-Origin
Access-Control-Allow-Origin: * позволяет рисовать иконки на canvas и загружать их с любого источника (origin).

Кэширование и актуальность

Каждая иконка хранится в Cloudflare R2 и в edge-кэше дата-центра, который её отдал. Повторные запросы обычно занимают несколько миллисекунд.

Сохранённые иконки обновляются в фоне через семь дней, поэтому, если сайт сменит логотип, иконка обновится автоматически и никого не замедлит.

Если у сайта вообще нет иконки, этот результат запоминается на час, чтобы не заваливать сайт повторными запросами.

Иконка по умолчанию

Если иконка недоступна, API возвращает эту нейтральную заглушку. Чтобы распознать её, проверьте, имеет ли заголовок X-Source значение default.

cURL
$ curl -I https://favicon.is/example.invalid

HTTP/2 200
content-type: image/svg+xml
x-source: default
x-reason: unsupported-tld

API проверки иконок (JSON)

Проверка фавиконов работает на JSON-эндпоинте, который перечисляет все иконки, объявленные сайтом: теги link, манифест веб-приложения и /favicon.ico — с реальными размерами в пикселях.

JSON
GET https://favicon.is/api/inspect?domain=github.com

{
  "domain": "github.com",
  "url": "https://github.com/",
  "title": "GitHub · Build and ship software on a single, collaborative platform",
  "reachable": true,
  "icons": [
    {
      "href": "https://github.githubassets.com/favicons/favicon.svg",
      "rel": "icon",
      "type": "image/svg+xml",
      "source": "link",
      "ok": true,
      "contentType": "image/svg+xml",
      "width": 32,
      "height": 32
    }
  ],
  "manifest": { "href": "https://github.com/manifest.json", "ok": true, "icons": [ … ] },
  "checks": { "ico": true, "svg": true, "appleTouch": true, "manifest": true, "large": true }
}
Проверка фавиконов

Честное использование

Эндпоинт изображений бесплатен и при обычном использовании не имеет жёстких ограничений. API проверки ограничен 30 запросами в минуту с одного IP-адреса. Если вы планируете отправлять миллионы запросов в день, пожалуйста, сначала свяжитесь с нами.