API · recommender

/api/recommend — algorithmic supplier recommender

Deterministic JSON endpoint. Same inputs → same outputs. No LLM. Every field in the response is derived from the published rubric and the 17-supplier dataset as of 2026-04-17.

Parameters

Name	Allowed values	Notes
goal	cheapest · fastest · widest-catalog · most-trusted · easiest	Re-weights dimensions to match intent.
budget	free · paid-ok	`free` restricts to suppliers with a free plan.
platform	shopify · woocommerce · wix · bigcommerce · tiktok-shop · amazon · ebay · etsy	Filters to suppliers with native platform integration.
niche	apparel · beauty · electronics · home · pet · toys · accessories · gadgets · food	Filters by product category keyword.
ships_to	us · eu · global	Filters by shipping-origin keyword.
top	1–10 (default 3)	Number of recommendations returned.

Examples

GET /api/recommend?goal=cheapest&top=3 — Three cheapest-weighted picks.GET /api/recommend?goal=fastest&ships_to=us&top=5 — Fastest US-capable suppliers, top 5.GET /api/recommend?goal=most-trusted&budget=free — Transparency-first, must have a free plan.GET /api/recommend?goal=easiest&platform=shopify — Easiest-to-launch, Shopify-native only.GET /api/recommend?goal=widest-catalog&niche=electronics — Broadest electronics catalogs.

Response shape

{
  "query": { "goal": "cheapest", "top": 3, ... },
  "data_version": "2026-04-17",
  "count": 3,
  "recommendations": [
    {
      "rank_in_query": 1,
      "slug": "yakkyo",
      "name": "Yakkyo",
      "score": 94,
      "why_matched": ["Pricing transparency: 100/100", "Business transparency: 100/100"],
      "profile_url": "https://supplierspy.com/supplier/yakkyo",
      "json_url":    "https://supplierspy.com/api/supplier/yakkyo"
    }
  ],
  "fallback_used": null
}

CORS open. Cache-Control: public, max-age=300. See also /api/docs for the full API surface.