API リファレンス

1つのエンドポイント、いくつかのコントロール、2つの認証方式。

リファレンス前に移行パスが必要ですか?

まずClearbit 代替ガイドまたはlogo API バイヤーズガイドをご覧ください。

ClearLogo は単一の HTTP エンドポイント GET /logo/{domain} を公開し、ドメインのロゴを一貫した比率・不透明な背景の PNG (または WebP/JPEG) として返します。背景はテーマに合わせて自動設定されます (ライトは白、ダークはダークニュートラル)。匿名アクセスは低ボリュームのテストで動作し、本番トラフィックではブラウザキー (クライアント) またはサーバーキー (バックエンド) を使用します。

エンドポイント

GET https://api.clearlogo.dev/logo/:domain

:domain はスキームやパスのない名前付きホスト名です。例えば github.com。API はデフォルトで image/png を返します。

クエリパラメータ

名前	型	デフォルト	注記
`size`	number	`128`	出力の寸法 (ピクセル単位)。正方形のみ。許可される値: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024。
`frame`	`fill, original`	`fill`	`fill` はロゴのビジュアルコンテンツでキャンバスを埋め、元のホワイトスペースを除去します。`original` はソースアイコン本来のフレーミングと比率を保持します。
`padding`	number	`10`	フレームされたコンテンツ周囲の各辺の余白。キャンバスの % で指定 (0–20、ステップ 5)。
`shape`	`square, circle`	`square`	`square` は標準フレーミングです。`circle` はロゴを内接円にフィットさせ、円形アバターでクリップされないようにします — 出力は依然として正方形の画像で、透過マスクは適用されません。
`part`	`full, logo, text`	`full`	返すロゴのパーツを選択します — `full`（ロゴ全体）、`logo`（アイコン/マーク）、`text`（ワードマーク） — ロゴが分割されているドメイン向けです。指定したパーツが利用できない場合はロゴ全体にフォールバックします（個別パーツとして管理されているロゴの場合は透過画像が返されます）。パーツはラスター (PNG) の場合があり、実際の色で描画されます。
`format`	`png \| webp \| jpeg`	`png`	出力フォーマット。省略時は `Accept` ヘッダーで自動ネゴシエーションされます。モダンブラウザでは `<img>` 使用時に WebP が自動返却されます。
`theme`	`light \| dark`	`light`	利用可能な場合はダークバリアントを返します。利用できない場合はライトにフォールバックします。不透明な背景色も設定します: `light` では白、`dark` ではダークニュートラル。
`token`	string	—	クライアントコードから使用されるブラウザキー。Origin または Referer はキーで許可されているドメインと一致する必要があります。

代表的なリクエスト例:

GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square

part で分割ロゴのアイコン/マークだけをリクエストする場合:

GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo

認証

匿名リクエストは低量テスト用に機能します。本番トラフィックの場合は、ブラウザキー (クライアント) またはサーバーキー (バックエンド) を使用します:

ブラウザ

<img
  src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
  alt="" />

サーバー

curl \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  "https://api.clearlogo.dev/logo/example.com"

レート制限

キーごとの制限は X-RateLimit-* ヘッダーで返されます。超過した場合、API は 429 で応答し、Retry-After ヒントを含めます。

よくある質問

ドメインのロゴを取得するには?

https://api.clearlogo.dev/logo/{domain} に GET リクエストを送信してください。{domain} は github.com のような名前付きホスト名です。低ボリュームのテストにはログインは不要で、応答はデフォルトで PNG なので <img> タグで直接使用できます。

ブラウザキーとサーバーキーの違いは?

ブラウザキーはフロントエンドコードや <img> タグに含めても安全です。リクエストはキーで設定された許可ドメインに対して検証されます。サーバーキーはバックエンドからの Authorization: Bearer ヘッダーで認証し、ブラウザに送信してはいけません。

サポートされる出力フォーマットは?

png (デフォルト)、webp、jpeg の 3 つをサポートしています。format パラメータを省略すると、リクエストの Accept ヘッダーから自動ネゴシエーションされ、モダンブラウザで <img> を使用すると WebP が自動的に返されます。

レート制限の仕組みは?

キーごとの制限は X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset レスポンスヘッダーで返されます。制限を超えると HTTP 429 が返され、Retry-After ヒントで何秒待つべきかが示されます。

透過背景や正方形クロップは取得できますか?

出力は常に不透明な正方形の画像です — 透過バリアントはありません。背景は theme に合わせて設定されます: light では白、dark ではダークニュートラルです。その正方形キャンバス内でフレーミングを制御できます: frame (fill, original) でキャンバスをロゴのコンテンツで埋めるか、ソースアイコン本来の比率を保持するかを選択し、padding (0–20、ステップ 5) で各辺の余白を設定し、shape (square, circle) を circle にするとロゴが内接円にフィットします (出力は依然として正方形の画像)。ピクセル寸法には size (許可値: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) を使用します。ロゴが分割されているドメインでは、part (full, logo, text) でロゴ全体 (full、デフォルト)、アイコン/マーク (logo)、ワードマーク (text) を選択でき、指定パーツが利用できない場合はロゴ全体にフォールバックします（個別パーツとして管理されているロゴの場合は透過画像が返されます）。