Referensi API
Satu endpoint, beberapa pengatur, dua mode autentikasi.
Butuh jalur migrasi sebelum referensi?
Mulai dengan panduan pengganti Clearbit atau panduan pembeli logo API.
ClearLogo mengekspos satu endpoint HTTP,
GET /logo/{domain}, yang mengembalikan PNG (atau WebP/JPEG) dari logo domain dengan rasio konsisten pada latar belakang buram yang sesuai tema (putih untuk terang, netral gelap untuk gelap). Penggunaan anonim bekerja untuk pengujian volume rendah; traffic produksi menggunakan browser key (klien) atau server key (backend).
Endpoint
GET https://api.clearlogo.dev/logo/:domain
:domain adalah hostname murni tanpa skema atau path, misalnya github.com. API mengembalikan image/png secara default.
Parameter query
| Nama | Tipe | Default | Catatan |
|---|---|---|---|
size | number | 128 | Dimensi output dalam px. Persegi saja. Nilai yang diizinkan: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
frame | fill, original | fill | fill mengisi kanvas (dikurangi padding) dengan konten visual logo, membuang whitespace sumber. original mempertahankan framing dan proporsi asli ikon sumber, menjaga whitespace bergaya app-icon di sekitarnya. |
padding | number | 10 | Margin per sisi di sekitar konten yang dibingkai, sebagai % dari kanvas (0–20, langkah 5). |
shape | square, circle | square | square adalah framing standar. circle mengukur logo agar muat di dalam lingkaran yang tertulis sehingga tidak terpotong di avatar melingkar — output tetap berupa gambar persegi, tanpa transparency mask. |
part | full, logo, text | full | Memilih bagian logo mana yang akan disajikan — full (seluruh logo), logo (ikon/lambang), atau text (wordmark) — untuk domain yang logonya telah dipisah. Jika bagian yang diminta tidak tersedia, akan kembali ke logo penuh (atau mengembalikan gambar transparan untuk logo yang dikelola sebagai bagian terpisah). Bagian dapat berupa raster (PNG) dan dirender dalam warna aslinya. |
format | png | webp | jpeg | png | Format keluaran. Dinegosiasi otomatis dari header Accept ketika dihilangkan — browser modern menerima WebP secara otomatis melalui <img>. |
theme | light | dark | light | Mengembalikan varian gelap jika tersedia, jika tidak maka kembali ke terang. Juga mengatur latar belakang buram: putih untuk light, netral gelap untuk dark. |
token | string | — | Browser key yang digunakan dari kode klien. Origin atau Referer harus cocok dengan domain yang diizinkan di kunci. |
Permintaan tipikal menggunakan parameter utama:
GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square
Meminta hanya ikon/lambang dari logo yang dipisah menggunakan part:
GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo
Autentikasi
Permintaan anonim bekerja untuk pengujian volume rendah. Untuk traffic produksi, gunakan browser key (klien) atau server key (backend):
Browser
<img
src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
alt="" />
Server
curl \
-H "Authorization: Bearer YOUR_SERVER_KEY" \
"https://api.clearlogo.dev/logo/example.com"
Batas kecepatan
Batas per-kunci dikembalikan di header X-RateLimit-*. Ketika Anda melebihinya, API merespons dengan 429 dan menyertakan petunjuk Retry-After.
Pertanyaan yang sering diajukan
Bagaimana cara mendapatkan logo untuk sebuah domain?
Kirim permintaan GET ke https://api.clearlogo.dev/logo/{domain} di mana {domain} adalah hostname seperti github.com. Login tidak diperlukan untuk pengujian volume rendah. Respons adalah PNG secara default dan bekerja langsung di tag <img>.
Apa perbedaan antara browser key dan server key?
Browser key aman untuk dikirim dalam kode frontend dan tag <img>; permintaan divalidasi terhadap domain yang diizinkan yang Anda konfigurasikan pada kunci. Server key mengautentikasi melalui header Authorization: Bearer dari backend dan tidak boleh sampai ke browser.
Format output apa yang didukung?
png (default), webp, dan jpeg. Ketika parameter format dihilangkan, ClearLogo menegosiasikan konten dari header Accept permintaan — browser modern menerima WebP secara otomatis ketika API dimuat melalui tag <img>.
Apa batas kecepatannya?
Batas per-kunci dikembalikan di header respons X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Melebihi batas mengembalikan HTTP 429 dengan petunjuk Retry-After yang menunjukkan berapa detik untuk menunggu sebelum mencoba lagi.
Bisakah saya mendapatkan latar belakang transparan atau crop persegi?
Output selalu berupa gambar persegi yang buram — tidak ada varian transparan. Latar belakang sesuai dengan theme: putih untuk light dan netral gelap untuk dark. Di dalam kanvas persegi tersebut Anda mengontrol pembingkaian: frame (fill, original) memilih antara mengisi kanvas dengan konten logo atau mempertahankan proporsi asli ikon sumber, padding (0–20, langkah 5) mengatur margin per sisi, dan shape (square, circle) memasukkan logo di dalam lingkaran yang tertulis ketika diatur ke circle (tetap dirender pada gambar persegi). Gunakan size (diizinkan: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) untuk dimensi piksel yang tepat. Untuk domain yang logonya telah dipisah, part (full, logo, text) memilih seluruh logo (full, default), ikon/lambang (logo), atau wordmark (text), dengan kembali ke logo penuh jika bagian yang diminta tidak tersedia (atau gambar transparan untuk logo yang dikelola sebagai bagian terpisah).