Pular para o conteúdo
Favicon.is

Documentação da API

O Favicon.is é uma API HTTP simples que retorna o favicon de qualquer site como imagem. Não há chaves, SDKs nem cabeçalhos de rate limit para gerenciar.

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

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

Parâmetros de consulta

ParâmetroTipoPadrãoDescrição
sizeinteger128Tamanho 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
largerbooleanfalseRetorna um ícone em alta resolução (256 px). Equivale a size=256.?larger=true
originalbooleanfalseIgnora o cache de favicons do Google e lê o ícone declarado no HTML do próprio site.?original=true
downloadbooleanfalseEnvia 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.

Exemplo
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 suportados

Resposta

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

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

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

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

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 }
}
Verificador de favicon

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.