Référence API
Un point de terminaison, quelques paramètres, deux modes d'authentification.
Besoin d'un chemin de migration avant la référence ?
Commencez par le guide de migration Clearbit ou le guide de l'acheteur d'API de logo.
ClearLogo expose un seul point de terminaison HTTP,
GET /logo/{domain}, qui retourne un PNG (ou WebP/JPEG) du logo du domaine avec un ratio cohérent sur un fond opaque correspondant au thème (blanc pour le mode clair, un neutre sombre pour le mode sombre). L'usage anonyme fonctionne pour les tests à faible volume ; le trafic en production utilise une clé navigateur (client) ou une clé serveur (backend).
Point de terminaison
GET https://api.clearlogo.dev/logo/:domain
:domain est un nom d'hôte nu sans schéma ni chemin, par exemple github.com. L'API retourne image/png par défaut.
Paramètres de requête
| Nom | Type | Défaut | Notes |
|---|---|---|---|
size | number | 128 | Dimension de sortie en px. Carré uniquement. Valeurs autorisées : 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
frame | fill, original | fill | fill remplit le canevas (hors marge) avec le contenu visuel du logo, en supprimant les espaces blancs de la source. original préserve le cadrage et les proportions d'origine de l'icône source. |
padding | number | 10 | Marge par côté autour du contenu cadré, en % du canevas (0–20, étape 5). |
shape | square, circle | square | square est le cadrage standard. circle ajuste le logo pour qu'il tienne dans un cercle inscrit afin qu'il ne soit pas rogné dans un avatar circulaire — la sortie reste une image carrée, sans masque de transparence. |
part | full, logo, text | full | Sélectionne la partie du logo à servir — full (le logo entier), logo (l'icône/symbole) ou text (le logotype textuel) — pour les domaines dont le logo a été divisé. Si la partie demandée n'est pas disponible, le logo complet est utilisé en remplacement (ou une image transparente est retournée pour les logos gérés comme des parties séparées). Les parties peuvent être matricielles (PNG) et s'affichent dans leurs vraies couleurs. |
format | png | webp | jpeg | png | Format de sortie. Auto-négocié depuis l'en-tête Accept — les navigateurs modernes reçoivent WebP automatiquement via <img>. |
theme | light | dark | light | Retourne la variante sombre quand disponible, sinon revient à la version claire. Définit également le fond opaque : blanc pour light, un neutre sombre pour dark. |
token | string | — | Clé navigateur utilisée à partir du code client. L'origine ou l'en-tête Referer doit correspondre à un domaine autorisé sur la clé. |
Une requête typique utilisant les paramètres canoniques :
GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square
Demander uniquement l'icône/symbole d'un logo divisé avec part :
GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo
Authentification
Les requêtes anonymes fonctionnent pour les tests en faible volume. Pour le trafic en production, utilisez une clé navigateur (client) ou une clé serveur (backend) :
Navigateur
<img
src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
alt="" />
Serveur
curl \
-H "Authorization: Bearer YOUR_SERVER_KEY" \
"https://api.clearlogo.dev/logo/example.com"
Limites de débit
Les limites par clé sont retournées dans les en-têtes X-RateLimit-*. Quand vous les dépassez, l'API répond avec 429 et inclut un indice Retry-After.
Questions fréquentes
Comment obtenir un logo pour un domaine ?
Envoyez une requête GET à https://api.clearlogo.dev/logo/{domain} où {domain} est un nom d'hôte comme github.com. Aucune connexion n'est requise pour les tests à faible volume. La réponse est un PNG par défaut et fonctionne directement dans les balises <img>.
Quelle est la différence entre une clé navigateur et une clé serveur ?
Une clé navigateur peut être déployée sans danger dans le code frontend et les balises <img> ; les requêtes sont validées contre les domaines autorisés que vous configurez sur la clé. Une clé serveur s'authentifie via l'en-tête Authorization: Bearer depuis votre backend et ne doit jamais atteindre le navigateur.
Quels formats de sortie sont pris en charge ?
png (par défaut), webp et jpeg. Quand le paramètre format est omis, ClearLogo négocie le contenu à partir de l'en-tête Accept de la requête — les navigateurs modernes reçoivent WebP automatiquement quand l'API est chargée via une balise <img>.
Quelles sont les limites de débit ?
Les limites par clé sont retournées dans les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Dépasser la limite retourne HTTP 429 avec un indice Retry-After indiquant combien de secondes attendre avant de réessayer.
Puis-je obtenir un fond transparent ou un recadrage carré ?
La sortie est toujours une image carrée opaque — il n'existe pas de variante transparente. Le fond correspond au theme : blanc pour light et un neutre sombre pour dark. Dans ce canevas carré, vous contrôlez le cadrage : frame (fill, original) choisit entre remplir le canevas avec le contenu du logo ou préserver les proportions d'origine de l'icône source, padding (0–20, étape 5) définit la marge par côté, et shape (square, circle) ajuste le logo dans un cercle inscrit quand il est défini à circle (rendu quand même sur une image carrée). Utilisez size (valeurs autorisées : 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) pour la dimension exacte en pixels. Pour les domaines dont le logo a été divisé, part (full, logo, text) sélectionne le logo entier (full, par défaut), l'icône/symbole (logo) ou le logotype textuel (text), avec repli sur le logo complet si une partie n'est pas disponible (ou une image transparente pour les logos gérés comme des parties séparées).