Przejdź do treści
Favicon.is

Dokumentacja API

Favicon.is to proste API HTTP, które zwraca favicon dowolnej strony jako obraz. Bez kluczy, bez SDK i bez nagłówków limitów, którymi trzeba się przejmować.

Endpoint

Wyślij żądanie GET z domeną w ścieżce. Treścią odpowiedzi jest sam obraz, więc możesz użyć URL-a bezpośrednio w tagu <img>.

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

Parametry zapytania

ParametrTypDomyślnieOpis
sizeinteger128Rozmiar ikony w pikselach: 16, 32, 48, 64, 128 lub 256. Inne wartości są zaokrąglane do najbliższego obsługiwanego rozmiaru.?size=64
largerbooleanfalseZwraca ikonę w wysokiej rozdzielczości (256 px). Odpowiednik size=256.?larger=true
originalbooleanfalsePomija cache faviconów Google i odczytuje ikonę zadeklarowaną w HTML samej strony.?original=true
downloadbooleanfalseWysyła nagłówek Content-Disposition, dzięki czemu przeglądarka pobiera ikonę jako plik.?download=1

Akceptowane dane wejściowe

Możesz podać samą domenę, subdomenę, pełny URL lub internacjonalizowaną nazwę domeny. Protokoły, www., porty, ścieżki i parametry zapytania są usuwane automatycznie, a wielkość liter w domenie nie ma znaczenia.

Przykład
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/例子.中国

Walidacja domen na podstawie TLD z IANA

Favicon.is pobiera ikony tylko dla domen, których sufiks jest domeną najwyższego poziomu (TLD) delegowaną w bazie strefy głównej IANA (Root Zone Database). Na żądania z innymi sufiksami, takimi jak .local, .test czy literówki, od razu zwracana jest ikona domyślna – bez łączenia się z jakimkolwiek serwerem.

Zobacz wszystkie obsługiwane TLD

Odpowiedź

Udane żądanie zwraca HTTP 200 z obrazem (zwykle PNG, czasem ICO lub SVG). Jeśli nie uda się znaleźć ikony, nadal dostajesz HTTP 200 z ikoną domyślną, więc na twojej stronie nigdy nie pojawi się uszkodzony obrazek.

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

Nagłówki odpowiedzi

Content-Type
Format obrazu: image/png, image/x-icon, image/svg+xml, image/jpeg, image/gif lub image/webp.
Cache-Control
Przeglądarki i CDN mogą przechowywać ikony w cache przez jeden dzień i przez tydzień odświeżać je w tle.
X-Source
Skąd pochodzi ikona: cache-edge, cache-r2, google, live lub default.
X-Reason
Tylko przy ikonie domyślnej. Wyjaśnia przyczynę: invalid-domain, unsupported-tld, not-found lub failure-cache.
X-Response-Time
Ile czasu zajęło przetworzenie żądania po naszej stronie.
Access-Control-Allow-Origin
Access-Control-Allow-Origin: * pozwala rysować ikony na canvasie i pobierać je z dowolnego originu.

Cache i aktualność

Każda ikona jest przechowywana w Cloudflare R2 oraz w cache brzegowym centrum danych, które ją obsłużyło. Kolejne żądania trwają zwykle kilka milisekund.

Zapisane ikony są odświeżane w tle po siedmiu dniach, więc gdy strona zmieni logo, ikona zaktualizuje się automatycznie, nikogo nie spowalniając.

Gdy strona w ogóle nie ma ikony, ten wynik jest zapamiętywany na godzinę, aby nie zasypywać jej powtarzanymi zapytaniami.

Ikona domyślna

Gdy żadna ikona nie jest dostępna, API zwraca ten neutralny placeholder. Jeśli chcesz go wykryć, sprawdź, czy nagłówek X-Source ma wartość 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 inspekcji (JSON)

Tester faviconów korzysta z endpointu JSON, który wymienia wszystkie ikony zadeklarowane przez stronę: tagi link, manifest aplikacji webowej i /favicon.ico – wraz z rzeczywistymi wymiarami w pikselach.

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 }
}
Tester faviconów

Uczciwe korzystanie

Endpoint obrazów jest darmowy i przy normalnym użyciu nie ma sztywnego limitu. API inspekcji jest ograniczone do 30 żądań na minutę z jednego adresu IP. Jeśli planujesz wysyłać miliony żądań dziennie, najpierw się z nami skontaktuj.