# Search

> Suggestions by name as people type, from two letters.

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

Suggestions by name as people type: up to 8 brands, closest first, in Arabic or English, by other, short and former names too. Hamzas and diacritics don’t get in the way, and each result says what it matched. Search isn’t counted as a pull.

- `GET https://new.wasmenia.com/api/v1/search/suggest`

- **Counts as a pull**: No
- **Results**: Up to 8, closest first
- **Starts at**: 2 letters
- **Limit**: 90 a minute without a key

## What you get

### Every name

Arabic and English, other and short names, acronyms, former names and version titles.

### In Latin letters

An Arabic name written in Latin letters finds it too.

### Spelling doesn’t get in the way

Hamzas, taa marbuta, alif maqsura and diacritics: «الأتصالات» finds «الاتصالات».

### What it matched

`matchedKind` says which name matched, so you can show «former name» beside a result.

### Light

Slug, both names, thumbnail and verification: enough for a list, without the whole record.

### A slug to store

Each result has a `slug` to store and read the record with whenever you need.

## How it matches

It reads `q` and answers up to 8 brands, closest first, with `total`, the count of every match.

It matches the Arabic and English names, other and short names, acronyms, former names, version titles, and an Arabic name written in Latin letters. `matchedKind` says which of them matched.

It searches the Wasmenia archive only: not websites, not the web. What isn’t in the archive doesn’t appear.

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

### A route of yours that holds the key

Your page asks your server, and your server calls search with its key.

### Wait after the last letter

200 to 300 milliseconds, and cancel the previous request when a new letter arrives.

### Show the suggestions

A list that works by keyboard: arrows move, Enter picks, Esc closes.

### Store the slug

When the user picks a brand, store `slug`, and read its record if you need its logo and colours.

## The request

```bash
curl -sS -G 'https://new.wasmenia.com/api/v1/search/suggest' \
  -H "Authorization: Bearer $WASMENIA_API_KEY" \
  --data-urlencode 'q=الاتصالات'
```

```javascript
const url = new URL('/api/v1/search/suggest', 'https://new.wasmenia.com');
url.searchParams.set('q', 'الاتصالات');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.WASMENIA_API_KEY}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { total, items } = await res.json();
// items: up to 8, closest first. Keep items[n].slug to read the record.
```

```python
import os

import requests

res = requests.get(
    'https://new.wasmenia.com/api/v1/search/suggest',
    params={'q': 'الاتصالات'},
    headers={'Authorization': f"Bearer {os.environ['WASMENIA_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
items = res.json()['items']
```

## With an input field

```javascript
// In the page: it asks your route, never Wasmenia with your key.
let timer;
let pending; // the request still in flight, if any
input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(async () => {
    pending?.abort(); // a newer keystroke makes the older answer useless
    pending = new AbortController();
    try {
      const url = '/brand-suggest?q=' + encodeURIComponent(input.value);
      const res = await fetch(url, { signal: pending.signal });
      if (res.status === 429) return pauseFor(Number(res.headers.get('Retry-After') ?? 60));
      render(await res.json());
    } catch (e) {
      if (e.name === 'AbortError') return; // replaced by a newer request
      showError();
    }
  }, 250);
});
```

## The limit

90 requests a minute per address without a key, and your plan’s rate with one. Fewer than two letters answers empty and isn’t counted. With a wait between letters, a normal user stays well below the limit.

## Questions

### Does it search by website?

No. It searches names only. The website is in the record, in `website`.

### Why nothing for one letter?

One letter matches almost everything. From two letters results become useful; fewer answers an empty list.

### I want every result, not the first eight

Search is for suggesting as people type. For the full list use Lists with `q`, in pages of up to 50.

**A brand picker in a form**

Search as you type by keyboard, storing the slug, and handling 429.