Skip to content
Favicon.is

API documentation

Favicon.is is a simple HTTP API that returns the favicon of any website as an image. There are no keys, no SDKs and no rate-limit headers to manage.

Endpoint

Send a GET request with the domain as the path. The response body is the image itself, so you can use the URL directly in an <img> tag.

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

Query parameters

ParameterTypeDefaultDescription
sizeinteger128Icon size in pixels. One of 16, 32, 48, 64, 128 or 256; other values are rounded to the nearest supported size.?size=64
largerbooleanfalseReturn a high-resolution icon (256 px). Equivalent to size=256.?larger=true
originalbooleanfalseSkip Google’s favicon cache and read the icon declared in the website’s own HTML.?original=true
downloadbooleanfalseSend a Content-Disposition header so browsers download the icon as a file.?download=1

Accepted input

You can pass a bare domain, a subdomain, a full URL or an internationalized domain name. Protocols, www., ports, paths and query strings are removed automatically, and the domain is matched case-insensitively.

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

Domain validation with IANA TLDs

Favicon.is only fetches icons for domains whose suffix is a top-level domain delegated in the IANA Root Zone Database. Requests for other suffixes, such as .local, .test or typos, are answered with the default icon at once, without contacting any server.

See all supported TLDs

Response

A successful request returns HTTP 200 with the image (usually PNG, sometimes ICO or SVG). If no icon can be found, you still get HTTP 200 with the default icon, so your page never shows a broken image.

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

Response headers

Content-Type
The image format: image/png, image/x-icon, image/svg+xml, image/jpeg, image/gif or image/webp.
Cache-Control
Icons may be cached for one day by browsers and CDNs, and revalidated in the background for a week.
X-Source
Where the icon came from: cache-edge, cache-r2, google, live or default.
X-Reason
Only on the default icon. Explains why: invalid-domain, unsupported-tld, not-found or failure-cache.
X-Response-Time
How long the request took on our side.
Access-Control-Allow-Origin
Access-Control-Allow-Origin: * lets you draw icons on a canvas or fetch them from any origin.

Caching and freshness

Every icon is stored in Cloudflare R2 and in the edge cache of the data centre that served it. Repeat requests usually take a few milliseconds.

Stored icons are refreshed in the background after seven days, so a site that changes its logo is updated automatically without slowing anyone down.

When a site has no icon at all, that result is remembered for an hour to avoid hammering it with repeated lookups.

Default icon

When no icon is available, the API returns this neutral placeholder. Check the X-Source header for the value default if you want to detect it.

cURL
$ curl -I https://favicon.is/example.invalid

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

Inspect API (JSON)

The favicon checker is powered by a JSON endpoint that lists every icon a site declares: link tags, the web app manifest and /favicon.ico, including actual pixel dimensions.

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 }
}
Favicon Checker

Fair use

The image endpoint is free and has no hard limit for normal use. The inspect API is limited to 30 requests per minute per IP address. If you plan to send millions of requests a day, please get in touch first.