Zum Inhalt springen

Storefront

Result cards

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

Merchants design the search result card for each content type in the Searcio dashboard, with a visual builder. This endpoint delivers the published designs to search widgets as precompiled HTML and CSS, so a widget renders exactly what the merchant designed without shipping a rendering engine of its own.

Base: https://searcio.com/api/v1/sites/{site}, or key-relative https://searcio.com/api/v1 (the site is resolved from the search key).

Auth: search key (?key=sk_… or X-Search-Key). It works only on the site's own domain.


GET /card-templates

Param Type Default Notes
type string (≤ 100) None Only templates for one content type.
filter[lang] string None The page's language: the templates for it and those for every language. Without it, all templates.
key string None The search key (or X-Search-Key).

Each template carries lang, the language its texts are in, or null when it serves every language. On a multilingual shop, send the page's language, so an English page gets the English template with its "View" button and a German page the German one.

Served from a server-side cache and not metered as a search. Fetch the templates once per page load (or cache them on the client), not once per query.

Response: 200 OK

json
{
  "templates": [
    {
      "id": 12,
      "type": "product",
      "is_default": false,
      "priority": 1,
      "conditions": [
        { "field": "category", "operator": "equals", "value": "cap" }
      ],
      "html": "<a class=\"sct-12 sct-12-root\" href=\"{{url}}\">…</a>",
      "css": ".sct-12-root { … } @media (max-width: 767px) { … }"
    },
    {
      "id": 9,
      "type": "product",
      "is_default": true,
      "priority": 0,
      "conditions": [],
      "html": "…",
      "css": "…"
    }
  ]
}

Conditional templates come first (in ascending priority) and the default template comes last, so the array is already in evaluation order.

Widget rendering contract

For each search hit:

  1. Take the templates whose type matches the hit's type.
  2. Walk them in array order and use the first whose conditions all match the hit (is_default acts as the catch-all). If there is no template, use your built-in card markup.
  3. Inject the template's css once per template, for example in a <style> tag keyed by template id. All selectors are scoped under sct-{id}.
  4. Replace every {{field}} placeholder with the hit's HTML-escaped field value. Placeholders also appear inside src and href attributes. A missing field is replaced with an empty string.
  5. Remove any element whose data-sc-if attribute (a JSON array of conditions) does not fully match the hit. This is how conditional badges such as "SALE" work.
  6. If an element has data-sc-rating-field, set the CSS variable --sc-rating-percent on it to value / 5 * 100 percent.
  7. If an element has a data-sc-price attribute, compute and fill in its price display as described below.

The compiled CSS already holds the layout the builder draws, so the card looks the same on the site as in the builder: the card and its containers stack their children in a column, other components flow inline, and an image is a block no wider than its box. Each component's own styles come after these and win. Inside a card that links to the product, a button is compiled as a span, because a link cannot hold another link; the card takes the click.

Price components

A price component compiles to one wrapper carrying data-sc-price, the field mapping and the number format, and up to four child spans marked with data-sc-price-part="prefix|regular|current|suffix":

Attribute Meaning
data-sc-price-field Field holding the plain effective price (e.g. price).
data-sc-regular-field Field holding the original price before a sale (e.g. regular_price).
data-sc-sale-field Field that, when not empty, means the item is on sale (e.g. sale_price).
data-sc-min-field / data-sc-max-field Fields for a variable product's price range (e.g. price_min / price_max).
data-sc-currency Currency symbol, e.g. €. On a price set to the shop's currency it is already the symbol of the currency the plugin last reported (currency in the search configuration), filled in when the templates are served, so it follows the shop without the template being published again.
data-sc-currency-source shop on a price set to the shop's currency; absent on a price with its own symbol. Informational: the widget formats with data-sc-currency either way.
data-sc-currency-position before, before_space, after, or after_space.
data-sc-decimals Number of decimal places (0 to 4).
data-sc-decimal-sep Decimal separator, e.g. ,.
data-sc-thousand-sep Thousands separator, e.g. . (may be empty).

For a hit, decide in this order:

  1. Range: if the min and max fields are both present and differ, the product is variable. Show only the [data-sc-price-part="current"] span, set to the min field's value, with the "prefix" span (its compiled text, e.g. "ab" in a German template) before it. Hide "regular".
  2. Sale: otherwise, if the sale field is present and not empty, show "regular" (the regular field's value, which the template normally strikes through) followed by "current", set to the sale field's value. Hide "prefix".
  3. Plain: otherwise, show only "current", set to the price field's value. Hide "prefix" and "regular".

The prefix the merchant leaves empty is compiled in the template's language: "ab" in German, "from" in English, "à partir de" in French, "desde" in Spanish, "da" in Italian, "vanaf" in Dutch and "od" in Polish. A template without a language takes the site's first language.

The space after the prefix and after the regular price is drawn by the compiled CSS (::after), so setting a part's textContent keeps it, and a hidden part takes its space along.

Format every amount with the currency, decimals and separator attributes above (they mirror typical WooCommerce price settings) before writing it into the span. Hide a part with display: none rather than removing it, so it can be shown again when the card is rendered for another hit. Each part already has its own compiled class for the typography and colour the merchant chose, so the widget only sets textContent and toggles visibility, never inline styles.

Condition operators

exists, not_exists, equals, not_equals, gt, lt, contains, is_true and is_false. Multiple conditions are combined with AND. equals compares loosely as strings; gt and lt compare numerically.

Errors

Status When
401 Missing or invalid search key
403 Site disabled, or Origin not the site's own domain