엔드포인트
도메인을 경로로 지정해 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 파비콘 캐시를 건너뛰고 웹사이트 자체 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에서 하루 동안 캐시될 수 있으며, 일주일 동안 백그라운드에서 재검증됩니다.
- 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: * 덕분에 아이콘을 캔버스에 그리거나 모든 출처에서 가져올 수 있습니다.
캐시와 최신성
모든 아이콘은 Cloudflare R2와 해당 요청을 처리한 데이터 센터의 엣지 캐시에 저장됩니다. 반복 요청은 보통 몇 밀리초면 처리됩니다.
저장된 아이콘은 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 태그, 웹 앱 매니페스트, /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회 요청으로 제한됩니다. 하루에 수백만 건의 요청을 보낼 계획이라면 먼저 연락해 주세요.