Aller au contenu
Favicon.is

Documentation de l’API

Favicon.is est une API HTTP simple qui renvoie le favicon de n’importe quel site web sous forme d’image. Pas de clés, pas de SDK et pas d’en-têtes de limite de débit à gérer.

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>.

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

Paramètres de requête

ParamètreTypePar défautDescription
sizeinteger128Taille 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
largerbooleanfalseRenvoie une icône haute résolution (256 px). Équivaut à size=256.?larger=true
originalbooleanfalseIgnore le cache de favicons de Google et lit l’icône déclarée dans le HTML du site lui-même.?original=true
downloadbooleanfalseEnvoie 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.

Exemple
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 charge

Ré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
$ 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

En-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
$ curl -I https://favicon.is/example.invalid

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

API 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.

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 }
}
Vérificateur de favicon

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.