# Identity data

> Names, other names, colours, fonts and guidelines, as the archive keeps them.

Source: https://new.wasmenia.com/en/developers/products/brand-data

Everything the archive knows about a brand, in one record: its name in both languages and its other names, country, sector and type, website and accounts, its logo colours and where they came from, identity colours for print, fonts, guidelines and related brands. What it doesn’t know comes back `null`.

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

- **Counts as a pull**: One record per brand
- **Languages**: Arabic always, English when known
- **A missing field**: Empty or an empty list, never a guess
- **Colour source**: Editor, guidelines or extracted

## What you get

### Every name

The name in Arabic and English, and up to 12 other names the brand is known by.

### Logo colours and their source

With their role (primary, secondary…) and `colorsSource` saying where they came from.

### Identity colours for print

From the guidelines as written: RGB, CMYK, Pantone, proportion and tints.

### Fonts and guidelines

The identity’s fonts and their roles, and its published guidelines, usually PDF.

### Verification

`verified` is true when the team verified the brand officially and filled in its data.

### Related brands

Parent, subsidiary, former name, each with its slug so you can read its record.

## The fields

| Field | What it holds |
| --- | --- |
| `name` | The name in both languages. `ar` is always there; `en` may be `null`. |
| `aliases` | Other names the brand is known by, up to 12. |
| `description` | A short description in both languages, if written. |
| `country` and `city` | The two-letter country code, and the city. |
| `category` and `industry` | Sector and industry, each with a slug and a name. |
| `entityType` | The kind of organisation: government, company, university… |
| `website` and `social` | The website, and accounts by platform name. |
| `verified` | `true` when the brand is officially verified. |
| `colors` and `colorsSource` | The logo’s colours, and where they came from. |
| `identityColors` | The identity’s colours as its guidelines set them, with RGB, CMYK and Pantone. |
| `fonts` | The identity’s fonts. |
| `guidelines` | Published guidelines, usually PDF. |
| `related` | Related brands: parent, subsidiary, former name… |

> **Missing fields**
>
> Not every brand is complete. An unknown field comes back `null`, an empty list `[]`. Show what is there, and don’t fill the gap with a guess.

## 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.

### Read the record when you need it

When a user opens the brand, not for every brand in a list: a card only needs the list.

### Show what is there

Any field may be missing. Hide what came back `null` instead of writing «not available» everywhere.

### Pick the main colour

The colour whose `role` is `primary`, else the first, and a text colour that reads on it by contrast.

### Read again when it changes

Keep `updatedAt` with the record, and read again when the list shows a newer one.

## Reading the record

```bash
curl -sS 'https://new.wasmenia.com/api/v1/brands/stc' \
  -H "Authorization: Bearer $WASMENIA_API_KEY"
```

```javascript
const res = await fetch('https://new.wasmenia.com/api/v1/brands/stc', {
  headers: { Authorization: `Bearer ${process.env.WASMENIA_API_KEY}` },
});
if (res.status === 404) return null; // no published brand by that slug (not a pull)
if (res.status === 402) throw new Error('monthly pulls used'); // see X-Quota-Reset
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const brand = await res.json();

brand.name.ar;                       // always there
brand.name.en;                       // may be null
brand.currentVersion?.logo?.url;     // the current logo, or undefined
brand.colors.map((c) => c.hex);      // may be []
```

```python
import os

import requests

res = requests.get(
    'https://new.wasmenia.com/api/v1/brands/stc',
    headers={'Authorization': f"Bearer {os.environ['WASMENIA_API_KEY']}"},
    timeout=10,
)
if res.status_code == 404:
    brand = None
else:
    res.raise_for_status()
    brand = res.json()
    logo = (brand['currentVersion'] or {}).get('logo')
```

## The main colour and its text colour

`brand-swatch.js`

```javascript
/** The brand's main colour and a text colour that reads on it. */
export function brandSwatch(brand) {
  const main = brand.colors.find((c) => c.role === 'primary') ?? brand.colors[0];
  if (!main) return null; // no colours: keep your own
  return { background: main.hex, text: readableOn(main.hex), source: brand.colorsSource };
}

/** White or near-black, whichever contrasts more with `hex` (WCAG). */
function readableOn(hex) {
  const [r, g, b] = [1, 3, 5].map((i) => {
    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  });
  const l = 0.2126 * r + 0.7152 * g + 0.0722 * b;
  return 1.05 / (l + 0.05) >= (l + 0.05) / 0.05 ? '#ffffff' : '#111111';
}
```

## Questions

### Are the colours exact?

`colorsSource` says: `editor` set by an editor, `guidelines` from the identity guidelines, `extracted` taken from the file automatically and approximate. For print, use `identityColors`.

### What is the difference between logo and identity colours?

`colors` are the logo’s own colours. `identityColors` are the whole identity’s colours as its guidelines set them, and may include colours the logo doesn’t use.

### Why is the English name sometimes empty?

Some brands have no English name, or it hasn’t been written yet. Show the Arabic name when `en` is empty.

### How do I know a brand is official?

`verified` is true when the team verified the brand and filled in its data. It doesn’t mean the brand runs its page itself.

**The whole record**

Every field with its type and meaning, and what its absence means.