marketplace
GET /v1/marketplace/{vertical}/search
Filter, sort and page one vertical's live Zinn®s.
การยืนยันตัวตน
ส่ง API key เป็น bearer token เอนด์พอยต์นี้ไม่ได้ระบุสิทธิ์การใช้งานเฉพาะในข้อกำหนด ดังนั้นควรให้คีย์ของคุณมีสิทธิ์น้อยที่สุดเท่าที่จำเป็นและให้ตรวจสอบจากการตอบกลับแทนที่จะคาดเดา
ปลายทางนี้ไม่ต้องใช้รหัสองค์กร คีย์ของคุณระบุองค์กรที่เป็นเจ้าของอยู่แล้ว และการตอบกลับจะถูกจำกัดขอบเขตไว้เฉพาะองค์กรนั้น
ทดลองใช้เลย
แทนที่สิ่งใดๆ ที่อยู่ภายในวงเล็บแหลมด้วยค่าของคุณเอง และตัวยึดตำแหน่งคีย์ด้วยคีย์จากแดชบอร์ดของคุณ
curl -X GET https://api.zinndigital.com/v1/marketplace/{vertical}/search \
-H "Authorization: Bearer zdk_live_…"เข้าสู่ระบบแล้วใช่ไหม คอนโซล API ในแดชบอร์ดของคุณจะเติมรหัสองค์กรจริงและคีย์ของคุณเองโดยอัตโนมัติ และทำการส่งคำขอไปยัง API จริง เพื่อให้คุณเห็นผลลัพธ์ที่เป็นข้อมูลจริง เปิดจุดสิ้นสุดนี้ในคอนโซล API
รายละเอียด
docs/83 §2 step 4. Anonymous, single-variant, and answered entirely from the derived publication projection — never from the org-scoped authoring tables. ⛔ **The facet parameters are generic on purpose.** Fields are defined by staff in admin, so a typed parameter per filter would mean a spec change, an SDK regeneration and a deploy every time somebody added one — which is the exact property this milestone exists to remove. A filter is `facet=key:op:value`, repeated; values of the same key are OR-ed, different keys are AND-ed. ⛔ **A numeric filter requires `type`.** The promoted slot behind `da` holds a different field for every listing type, so asking `da:gte:50` across a whole vertical would compare a domain authority against whatever the next kind of listing stores in the same column — wrong, plausible, and impossible to notice. It is refused with 422. ⛔ **`declared`/`of` on every facet are not decoration.** A field added in schema v2 does not exist on v1 listings, so filtering on it silently excludes them and "DA ≥ 50" quietly becomes "and authored after the day DA was added". The two numbers are what let the page say "482 of 1,930 Zinn®s declare DA" instead of implying the other 1,448 failed the filter. ⛔ `total` is probed to 10,000 and `total_is_capped` says so. An exact count of a large filtered set costs as much as returning it.
พารามิเตอร์
| ชื่อ | ประเภท | จำเป็นต้องมี | ลักษณะของสิ่งนี้ |
|---|---|---|---|
vertical (path) | string | ใช่ | — |
locale (query) | string | ไม่ใช่ | Render every operator-authored string — field labels, help text, enum option labels — in this locale, falling back to the source language per string. ⛔ A query parameter rather… |
type (query) | string | ไม่ใช่ | A listing type key. Required before any facet filter can be applied. |
category (query) | string | ไม่ใช่ | A category path. Matches that category AND everything beneath it. |
q (query) | string | ไม่ใช่ | What the buyer typed. Truncated at 120 characters rather than refused — pasting an essay into a search box is not an attack. ⭐ Answered by **hybrid retrieval** (docs/83 §2a, own… |
facet (query) | string[] | ไม่ใช่ | `key:op:value`, repeatable. `op` is `gte`/`lte` for numbers and `eq` for choices and yes/no fields. |
sort (query) | string<newest, price, -price, rating, sales> | ไม่ใช่ | — |
cursor (query) | string | ไม่ใช่ | Keyset page marker from a previous response. Never an offset. |
limit (query) | integer | ไม่ใช่ | — |
การตอบกลับ
| ชื่อ | ประเภท | จำเป็นต้องมี | ลักษณะของสิ่งนี้ |
|---|---|---|---|
marketplace | object | ใช่ | — |
canonical_vertical | string | ไม่ใช่ | Set when the request used a SUPERSEDED slug — the segment this page should 301 to. `null` on the normal path. ⛔ A retired slug still RESOLVES rather than 404ing: docs/83 §6 puts… |
listing_type | string | ไม่ใช่ | — |
results | MarketplaceSearchCard[] | ใช่ | — |
next_cursor | string | ใช่ | Empty when there is no next page. Opaque — never build one by hand. |
total | integer | ใช่ | — |
total_is_capped | boolean | ใช่ | True when there are more than `total` results. The page renders "10,000+"; showing a flat "10,000" for a catalogue of two million would be false. |
sort | string | ใช่ | — |
sorts | string[] | ใช่ | The sorts this catalogue offers, served with the data so the storefront is not compiled against a copy of the list. |
facets | MarketplaceFacet[] | ใช่ | — |
query | string | ใช่ | What was actually searched for, after the filter language took its bite. Empty when no phrase was given. ⭐ Differs from what the buyer typed whenever `interpreted` is non-empty:… |
interpreted | string[] | ใช่ | Human-readable chips for filters INFERRED from the phrase rather than ticked on the rail — already in the requested locale. ⛔⛔ **Render these.** A search box that silently rewri… |
retrieval | string<lexical, trigram, semantic>[] | ใช่ | Which retrieval paths actually ran for this request (docs/83 §2a, D-W15-9). Empty when no phrase was given, or when the deployment has no retrieval objects. ⛔⛔ **Not diagnostics… |
ข้อผิดพลาดที่เอนด์พอยต์นี้สามารถส่งกลับได้
404 · 422