本文へスキップ
Favicon.is

APIドキュメント

Favicon.isは、あらゆるWebサイトのファビコンを画像として返すシンプルなHTTP APIです。APIキーもSDKも不要で、レート制限ヘッダーを管理する必要もありません。

エンドポイント

ドメインをパスに指定してGETリクエストを送信します。レスポンスボディは画像そのものなので、URLをそのまま<img>タグで使えます。

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

クエリパラメータ

パラメータ型デフォルト説明
sizeinteger128アイコンのサイズ(ピクセル)。16、32、48、64、128、256のいずれかで、その他の値は最も近い対応サイズに丸められます。?size=64
largerbooleanfalse高解像度アイコン(256 px)を返します。size=256と同じです。?larger=true
originalbooleanfalseGoogleのファビコンキャッシュを使わず、Webサイト自身のHTMLで宣言されたアイコンを読み込みます。?original=true
downloadbooleanfalseContent-Dispositionヘッダーを送信し、ブラウザでアイコンをファイルとしてダウンロードさせます。?download=1

受け付ける入力

ドメインのみ、サブドメイン、完全なURL、国際化ドメイン名のいずれも指定できます。プロトコル、www.、ポート、パス、クエリ文字列は自動的に除去され、ドメインは大文字・小文字を区別せずに照合されます。

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

IANA TLDによるドメイン検証

Favicon.isがアイコンを取得するのは、サフィックスがIANAルートゾーンデータベースで委任されているトップレベルドメインのドメインだけです。.local、.test、入力ミスなど、それ以外のサフィックスへのリクエストには、どのサーバーにも接続せず、ただちにデフォルトアイコンを返します。

対応TLDの一覧を見る

レスポンス

リクエストが成功すると、HTTP 200で画像(通常はPNG、ときにICOやSVG)を返します。アイコンが見つからない場合もHTTP 200でデフォルトアイコンを返すため、ページに画像切れが表示されることはありません。

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

レスポンスヘッダー

Content-Type
画像の形式。image/png、image/x-icon、image/svg+xml、image/jpeg、image/gif、image/webpのいずれかです。
Cache-Control
アイコンはブラウザやCDNで1日間キャッシュでき、さらに1週間はバックグラウンドで再検証されます。
X-Source
アイコンの取得元。cache-edge、cache-r2、google、live、defaultのいずれかです。
X-Reason
デフォルトアイコンの場合のみ付与され、その理由を示します。invalid-domain、unsupported-tld、not-found、failure-cacheのいずれかです。
X-Response-Time
サーバー側でリクエストの処理にかかった時間。
Access-Control-Allow-Origin
Access-Control-Allow-Origin: * により、アイコンをcanvasに描画したり、任意のオリジンから取得したりできます。

キャッシュと鮮度

すべてのアイコンは、Cloudflare R2と、配信したデータセンターのエッジキャッシュに保存されます。2回目以降のリクエストは通常数ミリ秒で完了します。

保存済みのアイコンは7日後にバックグラウンドで更新されます。サイトがロゴを変更しても、誰の表示速度も落とすことなく自動的に反映されます。

アイコンがまったくないサイトの場合は、その結果を1時間記憶し、繰り返しの検索でサイトに負荷をかけないようにしています。

デフォルトアイコン

アイコンが取得できない場合、APIはこのニュートラルなプレースホルダーを返します。検出したい場合は、X-Sourceヘッダーの値がdefaultかどうかを確認してください。

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)

ファビコンチェッカーは、サイトが宣言するすべてのアイコン(linkタグ、Webアプリマニフェスト、/favicon.ico)を実際のピクセルサイズとともに一覧表示するJSONエンドポイントで動いています。

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 }
}
ファビコンチェッカー

公正な利用

画像エンドポイントは無料で、通常の利用であれば厳密な上限はありません。Inspect APIはIPアドレスごとに毎分30リクエストまでに制限されています。1日に数百万件のリクエストを送信する予定がある場合は、事前にご連絡ください。