エンドポイント
ドメインをパスに指定してGETリクエストを送信します。レスポンスボディは画像そのものなので、URLをそのまま<img>タグで使えます。
https://favicon.is/{domain}<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">クエリパラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| size | integer | 128 | アイコンのサイズ(ピクセル)。16、32、48、64、128、256のいずれかで、その他の値は最も近い対応サイズに丸められます。?size=64 |
| larger | boolean | false | 高解像度アイコン(256 px)を返します。size=256と同じです。?larger=true |
| original | boolean | false | Googleのファビコンキャッシュを使わず、Webサイト自身のHTMLで宣言されたアイコンを読み込みます。?original=true |
| download | boolean | false | Content-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 -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 -I https://favicon.is/example.invalid
HTTP/2 200
content-type: image/svg+xml
x-source: default
x-reason: unsupported-tldInspect API(JSON)
ファビコンチェッカーは、サイトが宣言するすべてのアイコン(linkタグ、Webアプリマニフェスト、/favicon.ico)を実際のピクセルサイズとともに一覧表示する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日に数百万件のリクエストを送信する予定がある場合は、事前にご連絡ください。