marketplace
GET /v1/marketplace/{vertical}/search
Filter, sort and page one vertical's live Zinn®s.
אימות
שלח מפתח API כטוקן Bearer. נקודת קצה זו אינה מציינת הרשאת ספציפית במפרט, לכן הקצה למפתח שלך את המינימום הנדרש ובדוק את התגובה במקום להניח הנחות.
נקודת קצה זו אינה דורשת מזהה ארגון. המפתח שלך כבר מזהה את הארגון שאליו הוא שייך, והתגובה מוגבלת אליו בלבד.
נסה זאת
החלף כל דבר בסוגריים זוויתיים בערכים משלך, ואת מציין מיקום המפתח במפתח מלוח הבקרה שלך.
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, owner… |
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… |
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. ⛔⛔… |
שגיאות שנקודה קצה זו עשויה להחזיר
404 · 422