Okkular Visual Search Developer Guide

This guide shows, in plain language, how to call the public Visual Search endpoints so you can drop "similar items" widgets or discovery panels into your digital experiences. It complements the reference documentation at docs.okkular.io/api-guide.

What is Visual Search?

Visual Search is Okkular's similarity service that looks at a product's analysed imagery and attributes, then recommends other catalogue items that "look" alike. Common uses include:

• PDP modules such as "You may also like".
• Category discovery widgets that surface alternatives with matching print, sleeve length, or silhouette.
• Clienteling and styling tools where an agent needs quick substitutes for out-of-stock SKUs.

Existing capabilities

• Fetch visually similar SKUs for any analysed product.
• Limit or refine results with attribute-level filters (length, sleeve, pattern, material, etc.).
• Retrieve a ready-made taxonomy of attributes per SKU to drive your UI controls.
• Receive merchandising-ready metadata with every recommendation — for example: image URL, title, price, PDP link, and *published.

Who should read this?

• Front-end developers adding PDP or PLP recommendations.
• Middleware teams building personalization or campaign services.
• Partners integrating Okkular data into mobile apps, kiosks, or email tooling.

No knowledge of the internal platform is required-just an API key and the SKU you want to enrich.

Quick start checklist

• Base URL: https://api.okkular.io/v1
• Required header: x-api-key: <your key> (contact Okkular Support if you need one)
• All requests and responses are JSON.
• Use HTTPS only. Browsers and server-side apps are both supported.

You only need two endpoints in day-to-day builds:

Technical implementation guide

Step 1 - Capture the shopper's context

• Determine the SKU currently being viewed or the SKU a stylist typed in.
• Store the tenant API key securely; you will reuse it for every call.

Step 2 - Load available filters (optional but recommended)

1. Call GET /visual-search/{sku}/categories with the x-api-key header.
2. Render the response in your UI as dropdowns, pills, checkboxes, or chips.
3. When a shopper selects a tag, build the filters JSON shown later in this guide.

Step 3 - Request visually similar products

1. Call GET /visual-search/{sku}.
2. Include the encoded filters value if the shopper chose any tags; otherwise omit it.
3. Read the default_list object in order of the position value and display the items.

Step 4 - Respond to user interactions

• When a shopper toggles a filter, repeat Step 3 with the updated filter payload.
• Handle empty results gracefully (show a friendly "No similar items" message).

Step 5 - Fail-safe logic

• If any call returns 401/403, surface an authentication error and alert your operations team.
• If you see 404 Visual search not generated yet, fall back to popular items or hide the widget until processing completes.

1. Get visually similar products

GET /visual-search/{sku}
Headers: x-api-key
Optional query: filters=<URL-encoded JSON>

Use this call to populate a carousel or recommendation zone. The service returns a JSON object named default_list where each key is a similar SKU and each value contains display-ready details like image, title, price, product link, and its ranking position.

Simple cURL example

curl "https://api.okkular.io/v1/visual-search/PD1081_10" \
  -H "x-api-key: <your-key>"

With filters applied

curl "https://api.okkular.io/v1/visual-search/PD1081_10?filters=%7B%22womens-cardigans-length%22:%22long%22%7D" \
  -H "x-api-key: <your-key>"

Response highlights

{
  "default_list": {
    "SKU123": {
      "image_link": "https://cdn.example.com/SKU123.jpg",
      "title": "Artier Structured Cropped Sweatshirt",
      "price": "92.00",
      "link": "https://shop.example.com/products/SKU123",
      "position": 0,
      "published": true
    },
    "SKU456": { "...": "..." }
  },
  "default_selection": {
    "womens-cardigans-length": "long"
  }
}

• default_list: the items you should render in the exact order shown by the position property.
• default_selection: only present when you passed filters; use it to highlight which tags are active in your UI.
• Empty default_list with HTTP 200 simply means "no matches for that filter".

Common HTTP responses:

• 200 OK - results returned.
• 404 Product not found. - SKU was never analysed or is misspelled.
• 404 Visual search not generated yet. - analysis exists but similar items are still being prepared.
• 401/403 - missing or invalid API key.

2. List filterable categories for a SKU

GET /visual-search/{sku}/categories
Headers: x-api-key

Call this endpoint to learn which attributes can be used as filters for the selected SKU. Each entry includes the raw attribute name and an optional alias. Use the attribute names and tag values exactly as returned when you build the filters query for the main endpoint.

Example response

[
  {
    "category_name": "womens-cardigans-length",
    "alias_name": "Length",
    "attributes": [
      {"name": "long", "alias_name": "Longline"},
      {"name": "regular", "alias_name": null}
    ]
  },
  {
    "category_name": "womens-cardigans-sleeves",
    "attributes": [
      {"name": "sleeveless"},
      {"name": "half-sleeves"},
      {"name": "full-sleeves"}
    ]
  }
]

Typical use: load this list when the PDP or search page first renders, let the shopper pick the tags they care about, then call the main endpoint again with those selections encoded as filters.

3. Visual Search API details

Request breakdown

Building the filters parameter

The Visual Search endpoint accepts one optional query parameter called filters. Its value must be URL-encoded JSON. The JSON structure is:

{
  "womens-cardigans-length": "long"
}

Guidelines:

• Attribute names and tag values must match what /categories returned (case-insensitive, but lower-case everything for consistency).
• Pass multiple categories as additional key-value pairs in the JSON object if you want to combine filters (for example, sleeve length plus print).
• The service automatically limits the number of returned SKUs; you do not need to supply pagination parameters.

Response schema

Categories endpoint schema

4. Code examples

JavaScript (browser or Node.js)

async function fetchSimilarProducts({ sku, apiKey, filters }) {
  const params = new URLSearchParams();
  if (filters) {
    params.set('filters', encodeURIComponent(JSON.stringify(filters)));
  }
  const res = await fetch(`https://api.okkular.io/v1/visual-search/${sku}?${params}`, {
    headers: { 'x-api-key': apiKey }
  });
  if (!res.ok) throw new Error(`Visual search failed: ${res.status}`);
  return res.json();
}

// Example usage
fetchSimilarProducts({
  sku: 'PD1081_10',
  apiKey: window.OKKULAR_API_KEY,
  filters: {
    'womens-cardigans-length': 'long'
  }
}).then(renderCarousel);

Java (using OkHttp)

OkHttpClient client = new OkHttpClient();

String filtersJson = URLEncoder.encode(
  "{\"womens-cardigans-length\":\"long\"}",
    StandardCharsets.UTF_8);

Request request = new Request.Builder()
    .url("https://api.okkular.io/v1/visual-search/PD1081_10?filters=" + filtersJson)
    .header("x-api-key", System.getenv("OKKULAR_API_KEY"))
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) {
        throw new IOException("Unexpected code " + response);
    }
    String body = response.body().string();
    System.out.println(body);
}

PHP (cURL)

$apiKey = getenv('OKKULAR_API_KEY');
$sku = 'PD1081_10';
$filters = urlencode(json_encode([
  'womens-cardigans-length' => 'long'
]));

$ch = curl_init("https://api.okkular.io/v1/visual-search/$sku?filters=$filters");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["x-api-key: $apiKey"],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    throw new Exception(curl_error($ch));
}
curl_close($ch);

$data = json_decode($response, true);
print_r($data['default_list']);

Feel free to adapt these snippets to your preferred HTTP client-the only requirements are the base URL, the x-api-key header, and (optionally) the URL-encoded filters JSON.

5. Validations, errors, and exception handling

Additional validations performed automatically:

• Unpublished products are removed before the response is sent.
• Filters referencing unknown attribute names return a 200 with an empty result set (no error) so you can adjust the UI input.
• The backend caps the number of returned SKUs to the tenant-wide limit (SIMILAR_PRODUCTS_LIMIT), preventing oversized responses.

6. UI/UX flexibility

• You control the entire rendering layer. The API provides data only; styling, layout, and wording are fully up to your team.
• You may display all fields (image, title, price) or select a subset depending on the surface (PDP vs. email vs. kiosk).
• Filters can be exposed as dropdowns, toggles, chips, tabs, etc.-just ensure the values you send back match the exact attribute/tag names from the categories endpoint.
• You can mix Visual Search results with other recommendation strategies (for example, trending products) by merging arrays client-side while retaining the position field for the visual results subset.
• Because responses arrive as plain JSON, you can build native apps, responsive web components, or server-rendered HTML without additional SDKs.

7. Troubleshooting & tips

• Empty list? Results were filtered out. Remove or loosen filters to confirm the SKU has matches.
• 404 responses? Double-check the SKU spelling and confirm it has completed processing inside Okkular.
• Invalid API key? Regenerate or re-download the key from the Okkular dashboard, then update your environment variables or secrets store.
• UI best practice: Always respect the position field when ordering the carousel; do not sort alphabetically.
• Caching: You can cache results for short periods (for example, a few minutes) but refresh them after catalogue updates so shoppers see the latest matches.

8. Next steps

• Store your API key securely and wire it into your CI/CD secrets.
• Start with the /categories call to power your filter UI, then plug those selections into /visual-search/{sku}.
• Test edge cases such as unpublished items, empty filter responses, and invalid SKUs so your UX has friendly fallbacks.
• Reach out to support@okkular.io if you need higher rate limits, extra filter options, or help diagnosing responses.

Happy building!