Search

client.search — global search across players, guilds, items, and more.

Official docs: Search.

search(query, options?)

GET /search/:query

Option	Type	Description
only?	string	Restrict results, e.g. "player", "guild", "item"

Result keys are optional depending on matches. The echo query field always comes back.

type GlobalSearchResult = {
  query: string;
  players?: Record<string, string>; // uuid → username (or similar)
  guilds?: Record<string, { name: string; prefix: string }>;
  guildsPrefix?: Record<string, { name: string; prefix: string }>;
  items?: Item[]; // array — same `ItemList` as item quick-search, not a record
  territories?: Record<string, { start: unknown[]; end: unknown[] }>;
  discoveries?: Record<string, { start: unknown[]; end: unknown[] }>;
};

Unlike players / guilds, items is an array. Do not use Object.keys on it.

const { data } = await client.search.search("cabbage", { only: "item" });

console.log(data.query);
for (const item of data.items ?? []) {
  console.log(item.internalName, item.displayName, item.tier);
}

Narrowing with only

only value	Typical keys present
"player"	players
"guild"	guilds, guildsPrefix
"item"	items
omitted	whichever domains match

Use only when you know the domain — cheaper responses and clearer narrowing in your own code.

When not to use global search

Need	Prefer instead
Structured item filters	item.searchItems
Exact guild by prefix / UUID	guild.getGuildByPrefix
Full player profile	player.getPlayer

Global search is for discovery / autocomplete-style lookups, not deep filters.

Related

• Item for query + filter search
• Pagination (item search pages; global search is a single response)
• Runnable sample: examples/guild-and-search.ts