본문으로 건너뛰기
Favicon.is

API 문서

Favicon.is는 모든 웹사이트의 파비콘을 이미지로 반환하는 간단한 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 파비콘 캐시를 건너뛰고 웹사이트 자체 HTML에 선언된 아이콘을 읽습니다.?original=true
downloadbooleanfalse브라우저가 아이콘을 파일로 다운로드하도록 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
$ 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
$ 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 태그, 웹 앱 매니페스트, /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회 요청으로 제한됩니다. 하루에 수백만 건의 요청을 보낼 계획이라면 먼저 연락해 주세요.