> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osint.ly/llms.txt
> Use this file to discover all available pages before exploring further.

# Logo Service

> Fetch domain logos and country flags as images via a simple GET request.

The Osintly Logo Service returns logo images for any domain and country flags for supported aliases. Images are served directly from the edge with CORS enabled.

**Base URL:** `https://logos.osint.ly/{domain}`

**Flags URL:** `https://logos.osint.ly/flags/{alias}`

<CardGroup cols={3}>
  <Card title="No API key" icon="lock-open">
    No authentication required. Just a GET request.
  </Card>

  <Card title="CORS enabled" icon="globe">
    `Access-Control-Allow-Origin: *` — usable directly from any frontend.
  </Card>

  <Card title="Long-lived cache" icon="bolt">
    Logos are cached at the edge and in the browser. Fast on every request.
  </Card>
</CardGroup>

***

## Usage

### Basic request

```
GET https://logos.osint.ly/{domain}
```

Returns the logo image directly. No redirect.

```
https://logos.osint.ly/github.com
https://logos.osint.ly/stripe.com
https://logos.osint.ly/openai.com
```

The `www.` prefix is stripped automatically:

```
https://logos.osint.ly/www.github.com  →  same as github.com
```

***

## Flags

### Basic request

```
GET https://logos.osint.ly/flags/{alias}
GET https://logos.osint.ly/flags/{alias}.{format}
```

Returns the country flag image directly. The route accepts ISO codes, common country names in English and French, and frequent shortcuts like `uk`.

```
https://logos.osint.ly/flags/france.svg
https://logos.osint.ly/flags/fr
https://logos.osint.ly/flags/français.webp
https://logos.osint.ly/flags/uk.png
```

If the extension is omitted, `svg` is used by default:

```
https://logos.osint.ly/flags/france  →  same as /flags/france.svg
```

Supported formats:

* `svg`
* `png`
* `webp`
* `jpg`
* `jpeg` (`jpeg` is normalized to `jpg`)

`/flags` alone is invalid and returns `400`; a country alias is required.

***

## Integration

<CodeGroup>
  ```html HTML theme={null}
  <img src="https://logos.osint.ly/github.com" alt="GitHub logo" />
  ```

  ```html Flag theme={null}
  <img src="https://logos.osint.ly/flags/france.svg" alt="France flag" />
  ```

  ```css CSS theme={null}
  .logo {
    background-image: url('https://logos.osint.ly/github.com');
  }
  ```

  ```js JavaScript theme={null}
  const res = await fetch('https://logos.osint.ly/stripe.com');
  const blob = await res.blob();
  ```

  ```jsx React theme={null}
  <img src={`https://logos.osint.ly/${domain}`} alt={`${domain} logo`} />
  ```
</CodeGroup>

***

## HTTP responses

| Code  | Meaning                                                         |
| ----- | --------------------------------------------------------------- |
| `200` | Logo or flag found and returned                                 |
| `400` | Missing or invalid value in the URL                             |
| `404` | No image found for this request                                 |
| `429` | Too many requests — retry after 60 seconds                      |
| `405` | Method not allowed (only `GET`, `HEAD`, `OPTIONS` are accepted) |

***

## Response headers

| Header                        | Example value                             | Description                             |
| ----------------------------- | ----------------------------------------- | --------------------------------------- |
| `Content-Type`                | `image/png`, `image/svg+xml`              | MIME type of the returned image         |
| `Cache-Control`               | `public, s-maxage=2592000, max-age=86400` | Edge cache 30 days, browser cache 1 day |
| `Access-Control-Allow-Origin` | `*`                                       | CORS — no proxy needed                  |
| `X-Logo-Source`               | `hunter`, `google`, `r2`, `flagcdn`       | Source used to resolve the image        |

***

## Rate limiting

The service is limited to **1,000 requests per minute per IP** on requests that are not already in the edge cache. This limit may change over time.

When the limit is exceeded, the service returns:

```
HTTP 429 Too Many Requests
Retry-After: 60
```