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

# Text matching

> Exact name matching, word-phrase matching, how Chinese, Japanese and Korean text is matched, and why there is no substring search.

The API matches text in two ways. Neither is a substring or similarity search.

| Kind | Parameters | Matches |
| - | - | - |
| Exact | `mark_text`, `primary_owner_name`, `owner_name`, `representative_name`, `previous_owner_name`, and the `*_key` forms | The whole normalized value, and nothing else |
| Phrase | `mark_text_phrase`, `owner_name_phrase`, `representative_name_phrase` | Records where the words appear in order, anywhere in the field |

## Exact matching

Exact filters normalize your value the same way stored names are normalized (accents removed, punctuation turned into spaces, upper case, legal-form suffixes dropped; see [name keys](https://docs.pinakelai.com/concepts/parties.md#name-keys)), then compare the whole value.

* `mark_text=NOKY` finds marks whose text is `NOKY`, `Noky` or `noky`, and not `NOKY PLUS`.
* `owner_name=L'Oréal S.A.` finds owners whose key is `L OREAL`.

Each exact filter takes up to 20 values. The normalized value is cut to 512 characters.

## Phrase matching

`mark_text_phrase` searches the mark text, its translation and transliteration, and keywords the office assigned to the mark. `owner_name_phrase` and `representative_name_phrase` search party names and their translations. Each takes one value of 1 to 200 characters, which must contain at least one letter or digit.

### Latin, Cyrillic and other alphabetic scripts

Text is split into words, and the phrase matches whole words in order. Case does not matter.

| `mark_text_phrase` | Matches | Does not match |
| - | - | - |
| `nike` | NIKE, NIKE AIR, AIR NIKE | UNIKEN, NIKEA |
| `nike air` | NIKE AIR, NIKE-AIR, NIKE / AIR MAX | AIR NIKE, NIKEAIR |
| `at&t` | AT\&T, AT T | ATT |

Punctuation between words does not have to match: `nike air` also finds `NIKE-AIR`. Accents are not removed for you, so if a mark may be written with and without accents, search both spellings.

Apostrophes are kept inside words, so `l'oreal` is one word. The API searches both the straight (`'`) and the typographic (`’`) apostrophe for you.

### Chinese characters

Chinese characters, which Japanese also uses as kanji, are matched as an exact character sequence anywhere in the text. `科技` matches every mark containing those two characters next to each other, such as `华为科技` or `科技之光`. For Chinese text a phrase search therefore behaves like a substring search. Japanese hiragana is matched the same way.

A single common character or a two-character word can match hundreds of thousands of records. Narrow it with `jurisdiction`, a date range or another anchor such as `owner_key` (see below).

### Korean and katakana

A run of Korean hangul syllables, or of Japanese katakana, counts as one word and is matched like a Latin word: `삼성` matches `삼성 전자` but not `삼성전자`. Search the whole word as it is written in the mark, and search the variants you expect.

## No substring search

v1 has no substring, prefix, wildcard, fuzzy, phonetic or similarity search. Word matching is the right behaviour for brand searches in alphabetic scripts: `nike` should not return `UNIKEN`. Measured on a sample of about 52 million records, a whole-word search for `nike` returned 969 records where a substring match returned 3,127; the difference is words that merely contain those four letters.

If you need broader matching for a clearance pre-screen, search the distinctive words of the mark separately, and search known variants and translations. See [Clearance pre-screen](https://docs.pinakelai.com/use-cases/clearance-pre-screen.md).

## When a phrase matches too much

A phrase that matches more than 100,000 records gets 422 [`query-too-broad`](https://docs.pinakelai.com/errors/query-too-broad). Narrow it before retrying:

```bash theme={null}
# 422: 科技 alone matches too many records
--data-urlencode "mark_text_phrase=科技"

# Works: one register and recent filings
--data-urlencode "mark_text_phrase=科技" --data-urlencode "jurisdiction=CN" --data-urlencode "application_date_from=2024-01-01"

# Works: combined with an owner key
--data-urlencode "mark_text_phrase=科技" --data-urlencode "owner_key=腾讯科技 深圳 有限公司" --data-urlencode "jurisdiction=CN"
```

## When phrase search is unavailable

Phrase filters use full-text indexes. While an index is being rebuilt, or if it fails its health check, requests that use it get 503 [`search-index-unavailable`](https://docs.pinakelai.com/errors/search-index-unavailable). Exact filters and all other filters keep working, so a number or `mark_text` lookup is a good fallback.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.