Endpoint
Envie uma requisição GET com o domínio como caminho. O corpo da resposta é a própria imagem, então você pode usar a URL diretamente em uma tag <img>.
https://favicon.is/{domain}<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">Parâmetros de consulta
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| size | integer | 128 | Tamanho do ícone em pixels: 16, 32, 48, 64, 128 ou 256. Outros valores são arredondados para o tamanho suportado mais próximo.?size=64 |
| larger | boolean | false | Retorna um ícone em alta resolução (256 px). Equivale a size=256.?larger=true |
| original | boolean | false | Ignora o cache de favicons do Google e lê o ícone declarado no HTML do próprio site.?original=true |
| download | boolean | false | Envia um cabeçalho Content-Disposition para que o navegador baixe o ícone como arquivo.?download=1 |
Entradas aceitas
Você pode informar um domínio simples, um subdomínio, uma URL completa ou um nome de domínio internacionalizado. Protocolos, www., portas, caminhos e query strings são removidos automaticamente, e o domínio não diferencia maiúsculas de minúsculas.
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/例子.中国Validação de domínios com TLDs da IANA
O Favicon.is só busca ícones de domínios cujo sufixo seja um domínio de topo delegado no IANA Root Zone Database. Requisições com outros sufixos, como .local, .test ou erros de digitação, recebem o ícone padrão na hora, sem contatar nenhum servidor.
Ver todos os TLDs suportadosResposta
Uma requisição bem-sucedida retorna HTTP 200 com a imagem (geralmente PNG, às vezes ICO ou SVG). Se nenhum ícone for encontrado, você ainda recebe HTTP 200 com o ícone padrão, então sua página nunca exibe uma imagem quebrada.
$ 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: 3msCabeçalhos de resposta
- Content-Type
- O formato da imagem: image/png, image/x-icon, image/svg+xml, image/jpeg, image/gif ou image/webp.
- Cache-Control
- Navegadores e CDNs podem armazenar os ícones em cache por um dia e revalidá-los em segundo plano por uma semana.
- X-Source
- De onde o ícone veio: cache-edge, cache-r2, google, live ou default.
- X-Reason
- Apenas no ícone padrão. Explica o motivo: invalid-domain, unsupported-tld, not-found ou failure-cache.
- X-Response-Time
- Quanto tempo a requisição levou do nosso lado.
- Access-Control-Allow-Origin
- Access-Control-Allow-Origin: * permite desenhar os ícones em um canvas ou buscá-los de qualquer origem.
Cache e atualização
Cada ícone é armazenado no Cloudflare R2 e no cache de borda do data center que o entregou. Requisições repetidas costumam levar poucos milissegundos.
Os ícones armazenados são atualizados em segundo plano após sete dias, então um site que muda de logo é atualizado automaticamente, sem deixar nada mais lento para ninguém.
Quando um site não tem nenhum ícone, esse resultado fica registrado por uma hora para evitar sobrecarregá-lo com consultas repetidas.
Ícone padrão
Quando nenhum ícone está disponível, a API retorna este marcador neutro. Para detectá-lo, verifique se o cabeçalho X-Source tem o valor default.
$ curl -I https://favicon.is/example.invalid
HTTP/2 200
content-type: image/svg+xml
x-source: default
x-reason: unsupported-tldAPI de inspeção (JSON)
O verificador de favicon usa um endpoint JSON que lista todos os ícones declarados por um site: tags link, o web app manifest e o /favicon.ico, incluindo as dimensões reais em 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 }
}Uso justo
O endpoint de imagens é gratuito e não tem limite rígido para uso normal. A API de inspeção é limitada a 30 requisições por minuto por endereço IP. Se você pretende enviar milhões de requisições por dia, entre em contato antes.