Referencia de API
Un endpoint, algunos controles, dos modos de autenticación.
¿Necesitas una ruta de migración antes de la referencia?
Comienza con la guía de migración de Clearbit o la guía del comprador de logo API.
ClearLogo expone un único endpoint HTTP,
GET /logo/{domain}, que devuelve un PNG (o WebP/JPEG) del logo del dominio con proporción consistente sobre un fondo opaco adaptado al tema (blanco para claro, un neutro oscuro para oscuro). El uso anónimo funciona para pruebas de bajo volumen; el tráfico de producción usa una clave de navegador (cliente) o de servidor (backend).
Endpoint
GET https://api.clearlogo.dev/logo/:domain
:domain es un nombre de host sin esquema ni ruta, por ejemplo github.com. La API devuelve image/png por defecto.
Parámetros de consulta
| Nombre | Tipo | Por defecto | Notas |
|---|---|---|---|
size | number | 128 | Dimensión de salida en px. Solo cuadrado. Valores permitidos: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
frame | fill, original | fill | fill rellena el lienzo (menos el padding) con el contenido visual del logo, descartando el espacio en blanco de origen. original preserva el encuadre y las proporciones originales del icono fuente, conservando el espacio circundante al estilo de icono de app. |
padding | number | 10 | Margen por lado alrededor del contenido enmarcado, como % del lienzo (0–20, paso 5). |
shape | square, circle | square | square es el encuadre estándar. circle ajusta el logo dentro de un círculo inscrito para que no se corte en un avatar circular — la salida sigue siendo una imagen cuadrada, sin máscara de transparencia aplicada. |
part | full, logo, text | full | Selecciona qué parte del logo se sirve — full (el logo completo), logo (el icono/marca) o text (el logotipo de texto) — para dominios cuyo logo ha sido dividido. Si la parte solicitada no está disponible, se usa el logo completo como alternativa (o se devuelve una imagen transparente para logos gestionados como partes separadas). Las partes pueden ser rasterizadas (PNG) y se muestran en sus colores reales. |
format | png | webp | jpeg | png | Formato de salida. Negociado automáticamente desde el encabezado Accept — los navegadores modernos reciben WebP automáticamente con <img>. |
theme | light | dark | light | Devuelve la variante oscura cuando está disponible; de lo contrario, recurre a clara. También establece el fondo opaco: blanco para light, un neutro oscuro para dark. |
token | string | — | Clave de navegador utilizada desde código cliente. El origen o Referer debe coincidir con un dominio permitido en la clave. |
Una solicitud típica con los parámetros principales:
GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square
Solicitar solo el icono/marca de un logo dividido con part:
GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo
Autenticación
Las solicitudes anónimas funcionan para pruebas de bajo volumen. Para tráfico de producción, usa una clave de navegador (cliente) o una clave de servidor (backend):
Navegador
<img
src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
alt="" />
Servidor
curl \
-H "Authorization: Bearer YOUR_SERVER_KEY" \
"https://api.clearlogo.dev/logo/example.com"
Límites de velocidad
Los límites por clave se devuelven en encabezados X-RateLimit-*. Cuando los superas, la API responde con 429 e incluye una sugerencia de Retry-After.
Preguntas frecuentes
¿Cómo obtengo un logo para un dominio?
Envía una solicitud GET a https://api.clearlogo.dev/logo/{domain} donde {domain} es un nombre de host como github.com. No se requiere inicio de sesión para pruebas de bajo volumen. La respuesta es un PNG por defecto y funciona directamente en etiquetas <img>.
¿Cuál es la diferencia entre una clave de navegador y una de servidor?
Una clave de navegador es segura para enviar en código frontend y etiquetas <img>; las solicitudes se validan contra los dominios permitidos que configuras en la clave. Una clave de servidor se autentica mediante el encabezado Authorization: Bearer desde tu backend y nunca debe llegar al navegador.
¿Qué formatos de salida son compatibles?
png (por defecto), webp y jpeg. Cuando se omite el parámetro format, ClearLogo negocia el contenido desde el encabezado Accept de la solicitud — los navegadores modernos reciben WebP automáticamente cuando la API se carga vía <img>.
¿Cuáles son los límites de velocidad?
Los límites por clave se devuelven en los encabezados de respuesta X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Superar el límite devuelve HTTP 429 con una sugerencia Retry-After que indica cuántos segundos esperar antes de reintentar.
¿Puedo obtener un fondo transparente o un recorte cuadrado?
La salida es siempre una imagen cuadrada opaca — no existe variante transparente. El fondo corresponde al theme: blanco para light y un neutro oscuro para dark. Dentro de ese lienzo cuadrado puedes controlar el encuadre: frame (fill, original) elige entre rellenar el lienzo con el contenido del logo o preservar las proporciones originales del icono fuente; padding (0–20, paso 5) establece el margen por lado; y shape (square, circle) ajusta el logo dentro de un círculo inscrito cuando se establece en circle (se sigue renderizando en una imagen cuadrada). Usa size (permitidos: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) para la dimensión exacta en píxeles. Para dominios cuyo logo ha sido dividido, part (full, logo, text) selecciona el logo completo (full, por defecto), el icono/marca (logo) o el logotipo de texto (text), usando el logo completo como alternativa cuando una parte no está disponible (o una imagen transparente para logos gestionados como partes separadas).