Search

Stateless, geo-first search for products or stores near a location. Returns a paginated, sorted list synchronously — ideal for building your own search UI. For a conversational, agent-driven experience, see Conversations.

Requires an API key and a location. See Base URL & authentication.

Location is compulsory

Every search is anchored to a center point and radius — results are drawn only from that local area. Provide the center as coordinates or a city:

Field	Type	Description
lat, lng	number	Center coordinates. Take precedence over city.
city	string	A city name, geocoded to a center (optionally scoped by country).
radiusKm	number	Search radius in km (0.1–500). Default `10`.
country	string	Restrict to sellers that serve this country (name or ISO code).

A request with no resolvable location returns 400.

GET/v1/search/products

GET/v1/search/stores

Query parameters

Field	Type	Description
q	string	Free-text query. Matched by multilingual relevance when embeddings are enabled, else lightweight text matching.
category	string	Restrict to a product/store category.
sort	string	stores only — `relevance`, `popular`, `recent`, or `top_rated`. Defaults to `popular` (or `relevance` with `q`).
verified	boolean	stores only — `true` returns only stores whose seller is Plugie-verified.
currency	string	products only — ISO-4217 currency for resolved prices.
page, pageSize	number	Pagination. `pageSize` 1–50 (default 20).

Example

curl

curl "https://api.plugie.ai/v1/search/products?q=office%20chair&city=Amsterdam&radiusKm=10&page=1" \
  -H "Authorization: Bearer plg_your_api_key"

Response

A page of local results in data, a capped remote tier (stores/ products that reach the buyer regardless of distance — ship nationwide or serve online, shown on page 1), and a meta object with pagination links.

Field	Type	Description
data	array	Local results, nearest/most-relevant first. Each item carries a `distanceKm`.
remote	array	Non-local items that still reach the buyer (`remote: true`, `distanceKm: null`). Page 1 only.
meta.page / pageSize / hasMore		Pagination state.
meta.center / radiusKm / locatedBy		The resolved center, radius, and how the location was determined (coords \| city \| country).
meta.links	object	`self`, `next`, `prev` — ready-made URLs for the same search on adjacent pages (`next`/`prev` are null at the ends).

json

{
  "data": [
    {
      "id": "665f…",
      "title": "Aero Ergonomic Office Chair — Black",
      "price": { "amount": 18900, "currency": "EUR" },
      "image": "https://cdn.plugie.ai/…",
      "category": "office chair",
      "ratingAvg": 4.6, "ratingCount": 12,
      "distanceKm": 2.4,
      "remote": false,
      "store": { "id": "660a…", "slug": "techworld", "name": "TechWorld" }
    }
  ],
  "remote": [],
  "meta": {
    "page": 1, "pageSize": 20, "hasMore": false,
    "center": [4.9041, 52.3676], "radiusKm": 10, "locatedBy": "city",
    "links": { "self": "…?page=1", "next": null, "prev": null }
  }
}

/v1/search/stores returns store-first items: the store's own identity is top-level (only published stores are listed), and the seller behind it is nested under seller.

json

{
  "data": [
    {
      "id": "660a…",
      "slug": "techworld",
      "name": "TechWorld",
      "description": "Ergonomic office furniture in Amsterdam.",
      "logoUrl": "https://cdn.plugie.ai/…",
      "coverUrl": "https://cdn.plugie.ai/…",
      "categories": ["office chair", "desk"],
      "distanceKm": 2.4,
      "remote": false,
      "ratingAvg": 4.6, "ratingCount": 12,
      "salesCount": 87,
      "verified": true,
      "businessRegistered": true,
      "seller": { "id": "6612…", "name": "TechWorld B.V." }
    }
  ],
  "remote": [],
  "meta": { "page": 1, "pageSize": 20, "hasMore": false, "center": [4.9041, 52.3676], "radiusKm": 10, "locatedBy": "city", "links": { "self": "…?page=1", "next": null, "prev": null } }
}

Notes

Prices are in the currency's minor units (e.g. cents).
Multilingual relevance (e.g. a Dutch query matching English listings) is active when the catalog is embedded; otherwise q uses lightweight text matching.
The remote tier ensures nationwide/online sellers aren't hidden by a small radius.