Эндпоинт
Отправьте GET-запрос, указав домен в пути. Тело ответа — это само изображение, поэтому URL можно использовать прямо в теге <img>.
https://favicon.is/{domain}<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">Параметры запроса
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| size | integer | 128 | Размер иконки в пикселях: 16, 32, 48, 64, 128 или 256. Другие значения округляются до ближайшего поддерживаемого размера.?size=64 |
| larger | boolean | false | Вернуть иконку в высоком разрешении (256 px). То же самое, что size=256.?larger=true |
| original | boolean | false | Пропустить кэш фавиконов Google и взять иконку, объявленную в HTML самого сайта.?original=true |
| download | boolean | false | Отправить заголовок 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 -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 -I https://favicon.is/example.invalid
HTTP/2 200
content-type: image/svg+xml
x-source: default
x-reason: unsupported-tldAPI проверки иконок (JSON)
Проверка фавиконов работает на JSON-эндпоинте, который перечисляет все иконки, объявленные сайтом: теги link, манифест веб-приложения и /favicon.ico — с реальными размерами в пикселях.
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-адреса. Если вы планируете отправлять миллионы запросов в день, пожалуйста, сначала свяжитесь с нами.