# Logo API

Get the logo of any company by providing its domain name. Returns the logo image directly.

<Callout type="info">
    No authentication is required for GET requests.
</Callout>

## Get Logo

```
GET https://logo.tomba.io/:domain
```

**Parameters:**

| Name   | Type   | Required | Description                        |
| ------ | ------ | -------- | ---------------------------------- |
| domain | string | Yes      | The domain name (e.g., `tomba.io`) |

Subdomains are automatically resolved to the root domain (e.g., `www.google.com` and `mail.google.com` both resolve to `google.com`).

**Query Parameters:**

| Name        | Type    | Default | Description                                                 |
| ----------- | ------- | ------- | ----------------------------------------------------------- |
| `s`         | int     | 80      | Image size in pixels (1-512). Square output.                |
| `size`      | int     | 80      | Alias for `s`.                                              |
| `greyscale` | boolean | false   | Returns a greyscale version of the logo when set to `true`. |
| `d`         | string  |         | URL-encoded URL of a custom default image.                  |
| `default`   | string  |         | Alias for `d`.                                              |

By default, images are presented at 80px by 80px if no size parameter is supplied. You may request a specific image size, which will be dynamically delivered from Tomba by using the `s=` or `size=` parameter and passing a single pixel dimension (since the images are square).

**Using an `<img>` tag:**

Since the endpoint returns the image directly, you can drop the URL straight into the `src` attribute of an `<img>` tag — no API key and no preprocessing required.

```html
<!-- Default (80x80) -->
<img src="https://logo.tomba.io/zynga.com" alt="zynga" width="80" height="80" />

<!-- Custom size (200x200) -->
<img
    src="https://logo.tomba.io/zynga.com?s=200"
    alt="zynga"
    width="200"
    height="200"
/>

<!-- Greyscale at 128px -->
<img
    src="https://logo.tomba.io/zynga.com?s=128&greyscale=true"
    alt="zynga"
    width="128"
    height="128"
/>

<!-- Custom default image when the logo is not found -->
<img
    src="https://logo.tomba.io/unknown.com?d=https%3A%2F%2Fexample.com%2Flogo.png"
    alt="Fallback"
    width="80"
    height="80"
/>
```

Rendered results for `tomba.io`:

| `?s=48`                                                                                                        | `?s=80` (default)                                                                                              | `?s=128`                                                                                                          | `?s=128&greyscale=true`                                                                                                          |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://logo.tomba.io/zynga.com?s=48" alt="Tomba logo 48px" style={{ width: "48px", height: "48px" }} /> | <img src="https://logo.tomba.io/zynga.com?s=80" alt="Tomba logo 80px" style={{ width: "80px", height: "80px" }} /> | <img src="https://logo.tomba.io/zynga.com?s=128" alt="Tomba logo 128px" style={{ width: "128px", height: "128px" }} /> | <img src="https://logo.tomba.io/zynga.com?s=128&greyscale=true" alt="Tomba logo greyscale" style={{ width: "128px", height: "128px" }} /> |

**Response Headers:**

| Header                | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `Content-Type`        | Image MIME type (`image/png`, `image/webp`, etc.)           |
| `Content-Disposition` | `attachment; filename="domain.ext"`                         |
| `Cache-Control`       | `public, max-age=86400` (24h for logos, 5min for defaults)  |
| `X-Cache`             | `hit` or `miss` (in-memory cache status)                    |

**Response:**

| Status | Description                                            |
| ------ | ------------------------------------------------------ |
| 200    | Logo image with `Content-Type: image/png\|webp\|avif`  |
| 400    | Invalid domain or invalid size parameter               |

## Default Image

When a domain has no matching Tomba logo, a default placeholder image is returned instead of a 404 error. The default image is a gray square with a "?" mark, sized according to the `s`/`size` parameter (or 80x80 by default).

If you'd prefer to use your own default image, supply the URL in the `d=` or `default=` parameter. The URL should be URL-encoded to ensure that it carries across correctly. When a custom default is provided and the logo is not found, the API proxies the image from your URL.

```bash
# Custom default image
curl "https://logo.tomba.io/unknown.com?d=https%3A%2F%2Fexample.com%2Fimages%2Favatar.jpg"

# Using default= alias
curl "https://logo.tomba.io/unknown.com?default=https%3A%2F%2Fexample.com%2Flogo.png"
```

<Callout type="caution">
    Only `https` URLs are accepted. Invalid URLs return a `400 Bad Request`.
</Callout>

## Examples

```bash
# Default size (80x80)
curl -O https://logo.tomba.io/zynga.com

# Custom size (200x200)
curl -O "https://logo.tomba.io/stripe.com?s=200"

# Using size= alias
curl -O "https://logo.tomba.io/google.com?size=128"

# Greyscale
curl -O "https://logo.tomba.io/zynga.com?greyscale=true"

# Greyscale with custom size
curl -O "https://logo.tomba.io/stripe.com?s=128&greyscale=true"

# Subdomain resolves to root domain
curl -O https://logo.tomba.io/www.google.com

# Unknown domain returns default placeholder
curl -O https://logo.tomba.io/unknown-domain.com
```