# Logos

> The current logo’s files and its older versions, in sizes ready to show and download.

Source: https://new.wasmenia.com/en/developers/products/logos

Every brand’s current logo with all its files: the primary, the symbol, the wordmark, and files for dark and light backgrounds, with its older versions and their dates. Each file has a thumbnail for lists, an original (usually SVG) for print, and a 1024 PNG.

- `GET https://new.wasmenia.com/api/v1/brands/{slug}`
- `GET https://new.wasmenia.com/api/v1/assets/{id}/thumb`
- `GET https://new.wasmenia.com/dl/{id}`

- **Counts as a pull**: Reading the record, not the images
- **Formats**: Original (usually SVG) · PNG 1024 · WebP
- **Thumbnail sizes**: 128, 256 and 512
- **Limit**: 30 records a minute without a key

## What you get

### A file for each use

Primary, symbol and wordmark, horizontal or vertical, in whichever language it is written. Each file says its use in `role`.

### The right background

`colorMode` says which background a file is drawn for: colour, one colour, dark or light.

### Sizes ready to use

A WebP thumbnail for every file, and 128, 256 or 512 from the thumbnail endpoint, so you never resize anything yourself.

### The original for print

Links to the original file and a 1024 PNG on the files domain, with your key.

### The identity’s history

Every published version with its logo and release date (and how precise it is), newest first.

### Stays current

Store the brand’s slug, not its file: when its new identity is published, your logo changes too.

## What’s in the record

Each brand has a current version in `currentVersion`, with its primary logo file `logo` and its other files `variants`. Every file is an object of the same shape:

| Field | What it holds |
| --- | --- |
| `url` | The original file, usually SVG. For showing; not counted as a download. |
| `thumbnailUrl` | A WebP whose longer side is 256, lighter for lists. |
| `downloadUrl` | The original on the files domain, for a «Download» button. |
| `png1024Url` | A PNG whose longer side is 1024 on the files domain, or `null` if none was made. |
| `width` and `height` | Size in pixels, or `null` for a vector without one. |

Each file in `variants` also says what it is: `role` (primary, symbol, wordmark, horizontal, vertical…), `colorMode` (`color`, `mono` for one colour, `dark` for dark backgrounds, `light` for light ones), `orientation`, and `language` for its lettering.

## Older versions

`versions` has every published version of the brand: the current one first, then newest to oldest. Each has its `logo`, its release date `releaseDate` with its precision in `releasePrecision`, and a link to its page in the archive. Details in [Versions and identity history](https://new.wasmenia.com/developers/docs/concepts/versions.md) (Arabic).

## How to use it

### Get a key

Open a developer account in the console and make a key. The free plan is enough to start, and the key stays on your server in an environment variable.

### Store the brand’s slug

From search or a list, store `slug` in your database, not the logo’s link.

### Read the record on your server

One request by slug gives every file and version. Keep the answer and read it again when `updatedAt` changes.

### Pick the file for the background

A file with the same `colorMode` if there is one, else the primary, with a dark tile behind a logo drawn for dark.

### Show the right size

The thumbnail in lists, the original on the brand’s page and in print. The name alone when there is no logo.

## Picking the file for a background

`logo-for.js`

```javascript
/**
 * The file to show on a light or dark ground: one made for that ground if the
 * brand has it, else its primary logo, with whether that needs a tile behind it.
 */
export function logoFor(brand, ground /* 'light' | 'dark' */) {
  const version = brand.currentVersion;
  if (!version) return null;

  const files = version.variants.filter((v) => v.asset?.url);
  const forGround = files.find((v) => v.colorMode === ground);
  const primary = files.find((v) => v.role === 'primary');
  const asset = (forGround ?? primary)?.asset ?? version.logo;
  if (!asset) return null;

  return {
    src: asset.url,                 // the original, usually SVG
    small: asset.thumbnailUrl,      // WebP, 256 on its longer side
    width: asset.width,             // null for a vector without a size
    height: asset.height,
    // A primary drawn for dark grounds, shown on a light page, needs a dark tile.
    tile: !forGround && primary?.colorMode === 'dark' ? 'dark' : null,
  };
}
```

## When there is no logo

```javascript
function brandMark(brand, ground) {
  const logo = logoFor(brand, ground);
  if (logo) {
    const img = document.createElement('img');
    img.src = logo.small ?? logo.src;
    img.alt = brand.name.ar;
    img.loading = 'lazy';
    return img;
  }
  // No logo yet: the name, never a made-up mark.
  const name = document.createElement('span');
  name.textContent = brand.name.ar;
  return name;
}
```

## What counts, and what doesn’t

- **Reading the record with your key** is one pull against the month; a 404 or a 308 isn’t counted.
- **Images from `thumbnailUrl` and `url`** are fixed files on the files domain: counted neither as pulls nor as downloads.
- **The thumbnail endpoint** in 128, 256 and 512 needs no key and isn’t counted.
- **`/dl`** is for a download a person clicks: it counts in the brand’s statistics and is limited to 120 a minute per address. Don’t use it to show images.

## Questions

### Why are the original links empty in the trial?

The trial on this page runs without a key, so the original file links come back `null` and the thumbnails stay. With your key every link arrives.

### What if a brand has no file for dark?

Show the primary on a light tile inside your dark background. Don’t invert the logo or turn it white yourself.

### Is the original always SVG?

Usually, not always: some logos were uploaded as images. Read `mime` on the file; `width` and `height` are `null` for a vector without a size.

### Should I show an old logo?

Show the current one, and an older one when the context is historical: a page on how an identity changed, or an archive of work published under an earlier logo.

**The right file for the background**

A short guide: a file for dark backgrounds when there is one, the name instead of the logo when there isn’t.