# Bazar

> Products, prices and stock from online stores (Venezuela first), for language models and web apps. Read-only and open: without an API key each address gets a small daily quota (REST requests and MCP tool calls; `RateLimit-*` headers say how much is left). An API key (`Authorization: Bearer bz_…`) gets a per-minute quota instead.

## MCP

- Endpoint: `/mcp` (Streamable HTTP, stateless). Tools: `search_products`, `get_listing`, `compare_prices`, `get_price_history`, `find_branches`, `get_exchange_rates`, `list_stores`.

Bazar knows the products, prices and stock of online stores (Venezuela first).
Data is synced from each store every few hours; nothing is fetched live.

- Start with search_products. Plain descriptions work ("algo para enfriar el cuarto"), and so do brands, models and barcodes. Queries are usually in Spanish.
- Results mix stores on purpose. Pass `stores` for one store (or a few to compare), `maxPerStore` to cap each store, `category` to keep one kind of product, `inStock` for what can be bought now.
- You may also write a store, a price range or "más barato" in `q` ("televisor en Damasco hasta 300 dólares"); `applied.interpreted` shows what was read. Parameters you pass always win. Every filter applied comes back in `applied`.
- For "the cheapest X", sort by price. If accessories show up (remotes for "televisor"), repeat with `category` set from `facets.categories`.
- Prices come as `amount` (decimal string, e.g. "69.00") plus `currency`. Venezuelan stores price in USD or VES; `converted` is the other one at the official BCV rate (with its `rate` and `rateDate`). Tell the user what the store charges and give the equivalent as an approximation. To filter or sort by price, set `currency`: offers in the other currency are converted so they compete too (`convert`).
- "¿Dónde está más barato?": when a result has `alsoSoldBy` above 0, call compare_prices with its `id`. It lists every store selling that barcode, in stock and cheapest first, with `savingsPercent`.
- "¿Subió de precio?": get_price_history. For bolívar prices read `convertedChangePercent`: a VES price that only follows the exchange rate is not a real increase.
- "¿A cuánto está el dólar?": get_exchange_rates (official BCV, and the parallel rate for reference).
- Pharmacies and hardware chains price and stock per branch or city. When the user says where they are, pass `city`, `subdivision` (ISO 3166-2, e.g. VE-A) or `latitude`/`longitude`; that leaves out stores that only sell online. Without a place, a chain shows its cheapest location (free-zone cities such as Porlamar can be cheaper), labeled in `location`. list_stores shows each store's cities.
- `match` says why a result appeared: identifier (exact barcode/SKU/model), all_terms, some_terms, or semantic (by meaning, without the words). Treat semantic matches as suggestions and check the title.
- `stale: true` means the store has not synced for a while, so availability is unknown.
- Use get_listing for the description, attributes and every offer of one result, and find_branches for addresses and hours ("¿dónde queda el Farmatodo más cercano?").
- Always give the user the product `url` so they can buy at the store.

## REST

- [OpenAPI](/docs/json): the full contract; the same names as the MCP tools' arguments.
- `GET /v1/search?q=…`: search (a store, a price range or "más barato" can be written in `q`), with `stores`, `category`, `maxPerStore`, `inStock`, `subdivision`, `city`, `latitude`/`longitude`/`radiusKm`, `currency`, `minPrice`, `maxPrice`, `sort`, `limit`, `cursor`.
- `GET /v1/listings/{id}`: one listing with its offers (one per branch or zone, when the store has them) and price history.
- `GET /v1/listings/{id}/history?days=&city=`: price changes, each also at that day's BCV rate, with the overall change.
- `GET /v1/compare?id=…` (or `gtin=`): every store selling the same barcode, cheapest first, in one currency.
- `GET /v1/branches?city=…` (or `latitude`/`longitude`): branches with address and hours, nearest first.
- `GET /v1/rates`: today's bolívar rates, official (BCV) and parallel.
- `GET /v1/stores`: stores, countries, currencies and the cities they have branches in.
- Errors are RFC 9457 problem details; `errors` names each invalid field.