---
title: "Search merchants/shops by free-text query (name or domain fragment), optionally filtered by country (ISO 3166-1 alpha-2, e.g. \"DE\") and/or by an EXACT category slug. Returns the public shop view only — shops still under internal review are never returned. `results` carries at most `limit` entries (default 50, max 100); `total_count` is the full match count before that cap and `truncated` is true when more results exist beyond this page — raise `offset` (default 0) to page through them. Multi-word queries are matched conjunctively: every word must be evidenced on a shop (name, domain or category). `ignored_terms` lists the words that matched nothing anywhere in the corpus and were therefore dropped to avoid an empty answer — a non-empty `ignored_terms` means the results answer a NARROWER question than you asked, so do not present them as satisfying those words. `match_quality` says how well the query was evidenced: \"full\" (every word found as a name/domain/category fragment — this is evidence of a fragment, NOT relevance, results are not ranked), \"partial\" (some words are in `ignored_terms`; the results answer a narrower question), \"none\" (no match). For \"partial\" and \"none\", `suggestions` carries hints instead of a guess: `categories` (slugs from `list_categories`, German words like \"schuhe\" are mapped, retry with `category`) and `shops` (domains within typo distance, e.g. \"bergzeitt\" -> bergzeit.de); both are empty for \"full\". `category_truncated` is true when category resolution hit its internal cap and the match set is a subset. `category`, if given, must be one of the slugs returned by `list_categories` — call that tool first, do not guess a slug; an unrecognized slug is rejected with an error (never a silent empty `results`). `category` is additive to `query` (AND, not OR) — pass `query: \"\"` to browse a category without a name/domain filter. If many shops match, grouping by country or category keeps the list scannable."
method: POST
path: "/tool/find_shop"
---

# Search merchants/shops by free-text query (name or domain fragment), optionally filtered by country (ISO 3166-1 alpha-2, e.g. "DE") and/or by an EXACT category slug. Returns the public shop view only — shops still under internal review are never returned. \`results\` carries at most \`limit\` entries (default 50, max 100); \`total_count\` is the full match count before that cap and \`truncated\` is true when more results exist beyond this page — raise \`offset\` (default 0) to page through them. Multi-word queries are matched conjunctively: every word must be evidenced on a shop (name, domain or category). \`ignored_terms\` lists the words that matched nothing anywhere in the corpus and were therefore dropped to avoid an empty answer — a non-empty \`ignored_terms\` means the results answer a NARROWER question than you asked, so do not present them as satisfying those words. \`match_quality\` says how well the query was evidenced: "full" (every word found as a name/domain/category fragment — this is evidence of a fragment, NOT relevance, results are not ranked), "partial" (some words are in \`ignored_terms\`; the results answer a narrower question), "none" (no match). For "partial" and "none", \`suggestions\` carries hints instead of a guess: \`categories\` (slugs from \`list_categories\`, German words like "schuhe" are mapped, retry with \`category\`) and \`shops\` (domains within typo distance, e.g. "bergzeitt" -> bergzeit.de); both are empty for "full". \`category_truncated\` is true when category resolution hit its internal cap and the match set is a subset. \`category\`, if given, must be one of the slugs returned by \`list_categories\` — call that tool first, do not guess a slug; an unrecognized slug is rejected with an error (never a silent empty \`results\`). \`category\` is additive to \`query\` (AND, not OR) — pass \`query: ""\` to browse a category without a name/domain filter. If many shops match, grouping by country or category keeps the list scannable.

`POST /tool/find_shop`

## Request

- Base URL: `https://api.openshopgraph.com`
- URL: `https://api.openshopgraph.com/tool/find_shop`
- Auth: one of:
  - none
  - API key in header `x-api-token`

## Request body

- object
  - `query` string, required
  - `country` string
  - `limit` number
  - `offset` number
  - `category` string

## Response `200`

OK

## Other responses

- `400`: invalid input
- `404`: not found

---

[API](https://skmtc.dev/openshopgraph/apis/openshopgraph-mcp-server.md) · [All operations](https://skmtc.dev/openshopgraph/apis/openshopgraph-mcp-server/llms.txt) · [OpenAPI document](https://skmtc.dev/openshopgraph/apis/openshopgraph-mcp-server/revisions/5a5ef86dcc0a?raw)