Vai al contenuto
Favicon.is

Documentazione API

Favicon.is è una semplice API HTTP che restituisce la favicon di qualsiasi sito come immagine. Niente chiavi, niente SDK e nessun header di rate limit da gestire.

Endpoint

Invia una richiesta GET con il dominio come percorso. Il corpo della risposta è l’immagine stessa, quindi puoi usare l’URL direttamente in un tag <img>.

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

Parametri di query

ParametroTipoPredefinitoDescrizione
sizeinteger128Dimensione dell’icona in pixel: 16, 32, 48, 64, 128 o 256. Gli altri valori vengono arrotondati alla dimensione supportata più vicina.?size=64
largerbooleanfalseRestituisce un’icona ad alta risoluzione (256 px). Equivale a size=256.?larger=true
originalbooleanfalseSalta la cache favicon di Google e legge l’icona dichiarata nell’HTML del sito.?original=true
downloadbooleanfalseInvia un header Content-Disposition, così il browser scarica l’icona come file.?download=1

Input accettati

Puoi passare un dominio semplice, un sottodominio, un URL completo o un nome di dominio internazionalizzato. Protocolli, www., porte, percorsi e query string vengono rimossi automaticamente e il dominio non distingue tra maiuscole e minuscole.

Esempio
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/例子.中国

Convalida dei domini con i TLD IANA

Favicon.is recupera le icone solo per i domini il cui suffisso è un dominio di primo livello delegato nell’IANA Root Zone Database. Le richieste con altri suffissi, come .local, .test o errori di battitura, ricevono subito l’icona predefinita, senza contattare alcun server.

Vedi tutti i TLD supportati

Risposta

Una richiesta riuscita restituisce HTTP 200 con l’immagine (di solito PNG, a volte ICO o SVG). Se non viene trovata nessuna icona, ricevi comunque HTTP 200 con l’icona predefinita, così la tua pagina non mostra mai un’immagine non funzionante.

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

Header di risposta

Content-Type
Il formato dell’immagine: image/png, image/x-icon, image/svg+xml, image/jpeg, image/gif o image/webp.
Cache-Control
Browser e CDN possono memorizzare le icone nella cache per un giorno e riconvalidarle in background per una settimana.
X-Source
La provenienza dell’icona: cache-edge, cache-r2, google, live o default.
X-Reason
Solo con l’icona predefinita. Ne spiega il motivo: invalid-domain, unsupported-tld, not-found o failure-cache.
X-Response-Time
Il tempo impiegato dalla richiesta sui nostri server.
Access-Control-Allow-Origin
Access-Control-Allow-Origin: * ti permette di disegnare le icone su un canvas o di recuperarle da qualsiasi origine.

Cache e aggiornamento

Ogni icona viene salvata in Cloudflare R2 e nella cache edge del data center che l’ha servita. Le richieste successive richiedono di solito pochi millisecondi.

Le icone salvate vengono aggiornate in background dopo sette giorni: se un sito cambia logo, l’icona si aggiorna automaticamente senza rallentare nessuno.

Quando un sito non ha alcuna icona, questo risultato viene memorizzato per un’ora, per evitare di sovraccaricarlo con ricerche ripetute.

Icona predefinita

Quando non è disponibile alcuna icona, l’API restituisce questo segnaposto neutro. Per riconoscerlo, controlla se l’header X-Source ha il valore 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 di ispezione (JSON)

Lo strumento di verifica favicon si basa su un endpoint JSON che elenca tutte le icone dichiarate da un sito: tag link, web app manifest e /favicon.ico, con le dimensioni reali in pixel.

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 }
}
Verifica favicon

Utilizzo equo

L’endpoint delle immagini è gratuito e non ha limiti rigidi per un uso normale. L’API di ispezione è limitata a 30 richieste al minuto per indirizzo IP. Se prevedi di inviare milioni di richieste al giorno, contattaci prima.