Endpoint
Envoyez une requête GET avec le domaine comme chemin. Le corps de la réponse est l’image elle-même : vous pouvez donc utiliser l’URL directement dans une balise <img>.
https://favicon.is/{domain}<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">Paramètres de requête
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
| size | integer | 128 | Taille de l’icône en pixels : 16, 32, 48, 64, 128 ou 256. Les autres valeurs sont arrondies à la taille prise en charge la plus proche.?size=64 |
| larger | boolean | false | Renvoie une icône haute résolution (256 px). Équivaut à size=256.?larger=true |
| original | boolean | false | Ignore le cache de favicons de Google et lit l’icône déclarée dans le HTML du site lui-même.?original=true |
| download | boolean | false | Envoie un en-tête Content-Disposition pour que les navigateurs téléchargent l’icône sous forme de fichier.?download=1 |
Entrées acceptées
Vous pouvez transmettre un domaine seul, un sous-domaine, une URL complète ou un nom de domaine internationalisé. Les protocoles, www., ports, chemins et chaînes de requête sont supprimés automatiquement, et le domaine est comparé sans tenir compte de la casse.
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/例子.中国Validation des domaines avec les TLD de l’IANA
Favicon.is ne récupère les icônes que pour les domaines dont le suffixe est un domaine de premier niveau délégué dans la base de données de la zone racine de l’IANA. Les requêtes pour d’autres suffixes, comme .local, .test ou des fautes de frappe, reçoivent immédiatement l’icône par défaut, sans contacter aucun serveur.
Voir tous les TLD pris en chargeRéponse
Une requête réussie renvoie un HTTP 200 avec l’image (généralement PNG, parfois ICO ou SVG). Si aucune icône n’est trouvée, vous recevez tout de même un HTTP 200 avec l’icône par défaut : votre page n’affiche jamais d’image cassée.
$ 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: 3msEn-têtes de réponse
- Content-Type
- Le format de l’image : image/png, image/x-icon, image/svg+xml, image/jpeg, image/gif ou image/webp.
- Cache-Control
- Les icônes peuvent être mises en cache un jour par les navigateurs et les CDN, et revalidées en arrière-plan pendant une semaine.
- X-Source
- La provenance de l’icône : cache-edge, cache-r2, google, live ou default.
- X-Reason
- Uniquement avec l’icône par défaut. Indique pourquoi : invalid-domain, unsupported-tld, not-found ou failure-cache.
- X-Response-Time
- Le temps de traitement de la requête de notre côté.
- Access-Control-Allow-Origin
- Access-Control-Allow-Origin: * vous permet de dessiner les icônes sur un canvas ou de les récupérer depuis n’importe quelle origine.
Cache et fraîcheur
Chaque icône est stockée dans Cloudflare R2 et dans le cache edge du centre de données qui l’a servie. Les requêtes répétées prennent généralement quelques millisecondes.
Les icônes stockées sont actualisées en arrière-plan au bout de sept jours : si un site change de logo, la mise à jour se fait automatiquement, sans ralentir personne.
Lorsqu’un site n’a aucune icône, ce résultat est mémorisé pendant une heure pour éviter de le surcharger de recherches répétées.
Icône par défaut
Lorsqu’aucune icône n’est disponible, l’API renvoie cette icône neutre. Pour la détecter, vérifiez si l’en-tête X-Source a la valeur default.
$ curl -I https://favicon.is/example.invalid
HTTP/2 200
content-type: image/svg+xml
x-source: default
x-reason: unsupported-tldAPI d’inspection (JSON)
Le vérificateur de favicon s’appuie sur un endpoint JSON qui liste toutes les icônes déclarées par un site : balises link, manifeste d’application web et /favicon.ico, avec leurs dimensions réelles en pixels.
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 }
}Usage raisonnable
L’endpoint d’images est gratuit et sans limite stricte pour un usage normal. L’API d’inspection est limitée à 30 requêtes par minute et par adresse IP. Si vous prévoyez d’envoyer des millions de requêtes par jour, contactez-nous d’abord.