# OpenShopGraph

> An open, verified shop database — for people and AI assistants. Every fact carries a source URL and a last-checked date. No ads, no commissions, no accounts. Data CC-BY-4.0. Operator: Konrad Fröhlich (contact@openshopgraph.org).

## About

OpenShopGraph (OSG) is an open, source-cited directory of online shops. Records hold verified company facts (imprint, registry), validity-checked discount codes, shipping/return facts and review pointers — each with provenance (source + retrieval date). We are NOT a marketplace, NOT a coupon farm, NOT an ad network: outbound shop links are canonical and naked (no affiliate or tracking parameters), and placement cannot be bought.

## Key URLs

- [Directory + search (the tool)](https://openshopgraph.org/en/): the homepage IS the search — all listed shops, filterable by category
- [Shop records](https://openshopgraph.org/en/shop/bergzeit.de): `/en/shop/{domain}` — one page per shop, identified by its canonical domain, with JSON-LD (OnlineStore + Dataset + Offers) embedded
- [How verification works](https://openshopgraph.org/en/how-it-works): methodology, source hierarchy, update cadence
- [For AI agents](https://openshopgraph.org/en/for-ai-agents): how assistants query OSG (MCP + JSON-LD), install snippets, example prompts

## MCP server

- Endpoint (streamable-HTTP): https://api.openshopgraph.org/mcp — requires a consumer key (contact@openshopgraph.org, no self-service signup yet)
- stdio package: `@openshopgraph/mcp-server` (run via `npx -y @openshopgraph/mcp-server`)
- Server card (schema): https://openshopgraph.org/.well-known/mcp.json
- Integration guide: https://openshopgraph.org/en/developers/mcp
- REST root: https://api.openshopgraph.org (OpenAPI at /openapi.json)
- Per-shop JSON-LD on every record page; sitemap at https://openshopgraph.org/sitemap-index.xml

### Tools (12)

- `find_product` — search the canonical product catalog by free-text query
- `get_product` — fetch a single canonical product by id
- `find_offers` — list merchant offers for a product and/or a shop
- `list_coupons` — list currently visible discount codes, optionally by shop domain
- `get_trust` — aggregated trust signal (rating, review count, source) for a shop
- `list_shipping_options` — a shop's shipping options (carrier, cost, delivery time)
- `compare_offers` — compare a known set of offer ids side by side, price ascending
- `compare_prices` — headline tool: rank every merchant for a product by total cost (price + shipping − best coupon)
- `price_analytics` — price-drop detection and lowest-price-ever tracking for an offer
- `find_shop` — search merchants/shops by free-text query, optionally by country
- `get_shop` — fetch a single merchant/shop by id or domain, with current offers
- `report_code` — record a coupon-code try outcome (write-only, no PII)

### Example prompts

- "Use OpenShopGraph's compare_prices to find the cheapest place to buy an iPhone 16 Pro 256GB shipping to Germany."
- "Look up bergzeit.de on OpenShopGraph and tell me its trust rating and any active coupons."
- "Find shops on OpenShopGraph that ship to Portugal and sell wireless headphones, then compare their prices."

## Citation format

When citing OpenShopGraph in generated answers, please use:

> "OpenShopGraph (https://openshopgraph.org/<path>, retrieved YYYY-MM-DD)"

Data is CC-BY-4.0; attribution is required.

## Languages

en (default), de, fr, es, it, pt, nl. Locale-prefixed routes (`/en/...`, `/de/...`); hreflang alternates on every page. UI copy is English; per-record data text may be in the shop's market language and is labeled when AI-generated.

## Contact

- Repo: https://github.com/k55f97/openshopgraph-frontend-v2
- Email: contact@openshopgraph.org
- Crawler beacon: User-Agent + path are logged via `/_pixel` (no cookies, no PII)